@@ -161,48 +161,60 @@ L<DBIx::Custom>はL<DBI>を補うとても便利なモジュールです。

 =head2 1. データベースへの接続

+まずL<DBIx::Custom>を読み込みます。

+

+    use DBIx::Custom;

+

 L<DBIx::Custom>オブジェクトを生成し、データベースに接続するには

 C<connect()>メソッドを使用します。

-    use DBIx::Custom;

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

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

+    my $dbi = DBIx::Custom->connect(

+        data_source => "dbi:mysql:database=dbname",

+        user => 'ken',

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

+        dbi_options => {mysql_enable_utf8 => 1}

+    );

-B<Data sourceのサンプル:>

+C<data_source>はデータベースシステムに応じたフォーマットで

+指定する必要があります。以下にデータベースごとのフォーマット

+方法のサンプルを掲載しておきます。

-MySQL

+B<MySQL>

     "dbi:mysql:database=$database"

     "dbi:mysql:database=$database;host=$hostname;port=$port"

-SQLite

+B<SQLite>

     "dbi:SQLite:dbname=$database"

     "dbi:SQLite:dbname=:memory:"

-PostgreSQL

+B<PostgreSQL>

     "dbi:Pg:dbname=$dbname"

-Oracle

+B<Oracle>

     "dbi:Oracle:$dbname"

     "dbi:Oracle:host=$host;sid=$sid"

-ODBC(Microsoft Access)

+B<ODBC(Microsoft Access)>

     "dbi:ODBC:driver=Microsoft Access Driver (*.mdb);dbq=hoge.mdb"

-ODBC(SQL Server)

+B<ODBC(SQL Server)>

    "dbi:ODBC:driver={SQL Server};Server=(local);database=test;Trusted_Connection=yes;AutoTranslate=No;"

+また認証が求められる場合は、C<user>とC<password>ユーザ名と

+パスワードを指定する必要があります。

+

 L<DBIx::Custom>はL<DBI>のラッパです。

-L<DBI>オブジェクトはC<dbh>で取得することができます。

+L<DBI>のデータベースハンドルはC<dbh>で取得することができます。

     my $dbh = $dbi->dbh;

-データベースハンドル属性にはデフォルトで次のものが設定されます。

+L<DBIx::Custom>ではデータベースハンドル属性にはデフォルトで次のものが設定されます。

     $dbi->dbh->{RaiseError} = 1;

     $dbi->dbh->{PrintError} = 0;

@@ -212,206 +224,199 @@ L<DBI>オブジェクトはC<dbh>で取得することができます。

 例外が発生しプログラムは終了します。

 またクエリが発行されると自動的にコミットされます。

-=head2 2. シュガーメソッド

+=head2 2. 挿入、更新、削除、選択のためのメソッド

 L<DBIx::Custom>は、

 C<insert()>、C<update()>、C<delete()>、C<select()>

-のようなシュガーメソッドを持っています。

-小さなことを行うのであれば、SQL文を

-作成する必要はありません。

+のような挿入、更新、削除、選択を行うためのメソッドを持っています。

+簡単なことをを行うのであれば、SQLを自分で記述する必要がありません。

 =head3 C<insert()>

-C<insert>メソッドです。データベースにデータを挿入します。

+データベースにデータを挿入するにはC<insert()>を使用します。

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

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

-これは次のL<DBI>の操作と同じです。

+C<table>にはテーブル名、C<param>には挿入したいデータを指定します。

-    my $sth = $dbh->prepare('insert into (title, author) values (?, ?);');

-    $sth->execute('Perl', 'Ken');

+次のSQLが発行されます。

+

+    insert into (title, author) values (?, ?);

 =head3 C<update()>

-C<update>メソッドです。データベースのデータを更新します。

+データベースのデータを更新するには、C<update()>を使用します。

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

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

                  where  => {id => 5});

-これは次のL<DBI>の操作と同じです。

+C<table>にはテーブル名、C<param>には挿入したいデータ、C<where>には

+条件を指定します。

-    my $sth = $dbh->prepare(

-        'update book set title = ?, author = ? where id = ?;');

-    $sth->execute('Perl', 'Ken', 5);

+次のSQLが発行されます。

+

+    update book set title = ?, author = ?;

 C<update>メソッドは安全のため

 where句のないSQLを発行することを許可していません。

 もしすべての行を更新したい場合は

-C<update_all()>メソッドを使用してください。

+C<update_all()>を使用してください。

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

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

 =head3 C<delete()>

-C<delete>メソッドです。データベースのデータを削除します。

+データベースのデータを1件削除するには、C<delete()>を使用します。

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

                  where  => {author => 'Ken'});

-これは次のL<DBI>の操作と同じです。

+C<table>にはテーブル名、C<where>には条件を指定します。

-    my $sth = $dbh->prepare('delete from book where id = ?;');

-    $sth->execute('Ken');

+次のSQLが発行されます。

+

+    delete from book where id = ?;

 C<delete>メソッドは安全のため

 where句のないSQLを発行することを許可していません。

 もしすべての行を削除したい場合は

-C<delete_all()>メソッドを使用してください。

+C<delete_all()>を使用してください。

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

 =head3 C<select()>

-C<select>メソッドです。テーブル名だけを指定しています。

+行を選択するにはC<select()>を使用します。

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

-これは次のL<DBI>の操作と同じです。

+C<table>だけを指定して、他の条件を指定しない場合は次のSQLが発行されます。

-    my $sth = $dbh->prepare('select * from book;);

-    $sth->execute;

+    select * from book;

 C<select()>メソッドの戻り値はL<DBIx::Custom::Result>

-オブジェクトです。C<fetch>メソッドを使用して

-行をフェッチすることができます。

+オブジェクトです。行をフェッチするにはC<fetch()>を使用します。

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

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

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

     }

+L<DBIx::Custom::Result>についてはこの後L<3. 行のフェッチ/"3. 行のフェッチ">で詳しく扱います。

+

+さまざまなC<select()>の使い方を見ていきましょう。

 次のC<select>は行の名前とwhere句を指定したものです。

     my $result = $dbi->select(

         table  => 'book',

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

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

         where  => {author => 'Ken'}

     );

-次のL<DBI>の操作と同じです。

-    

-    my $sth = $dbh->prepare(

-        'select author, title from book where author = ?;');

-    $sht->execute('Ken');

+C<column>には列名を、C<where>には条件を指定することができます。

+次のSQLが発行されます。

+

+    select author, title from book where author = ?;

-テーブルをjoinしたい場合はC<relation>を使用します。

+テーブルを結合したい場合ははC<relation>にテーブルの

+関係を記述します。

     my $result = $dbi->select(

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

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

+        where    => {book.name => 'Perl'},

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

     );

-次のL<DBI>の操作と同じです。

+bookテーブルのid列とrentalテーブルのbook_idが関連付けられます。

+次のSQLが発行されます。

-    my $sth = $dbh->prepare(

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

-        'where book.id = rental.book_id;');

-    $sth->execute;

+    select * from book, rental where book.name = ? and book.id = rental.book_id;

-SQL文の末尾に文字列を追加したい場合は<append>オプションを使用します。

+SQL文の末尾に文字列を追加したい場合は<append>を使用します。

     my $result = $dbi->select(

         table  => 'book',

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

-        append => 'order by price limit 5',

+        append => 'for update',

     );

-次のL<DBI>の操作と同じです。

+次のSQLが発行されます。

-    my $sth = $dbh->prepare(

-        'select * book where author = ? order by price limit 5;');

-    $sth->execute;

+    select * book where author = ? for update;

-C<append>オプションは、C<insert()>、C<update()>、C<update_all()>

-C<delete()>、C<select>メソッドで使用することが

-できます。

-

-この後のフィルタリングの解説で詳しく扱いますが、値をフィルタリングしたい

-場合はC<filter>オプションを使用することができます。

-

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

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

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

-                            author => 'encode_utf8'});

-

-C<filter>オプションは、C<insert()>、C<update()>、C<update_all()>

-C<delete()>、C<select>メソッドで使用することが

-できます。

-

-C<select()>メソッドのC<where>オプションではハッシュの代わりに

-タグを利用することもできます。これによって柔軟な

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

-

-    # Select, more flexible where

-    my $result = $dbi->select(

-        table  => 'book',

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

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

-    );

-

-タグについては以降で解説します。

+またC<append>は、C<select>だけでなくC<insert()>、C<update()>、C<update_all()>

+C<delete()>、C<delete_all()>、C<select()>で使用することもできます。

 =head2 3. 行のフェッチ

-C<select()>メソッドの戻り値であるL<DBIx::Custom::Result>

-には行をフェッチするためのさまざまなメソッドが

+C<select()>メソッドの戻り値はL<DBIx::Custom::Result>オブジェクトです。

+L<DBIx::Custom::Result>には行をフェッチするためのさまざまなメソッドが

 用意されています。

-(このセクションの解説では「配列」は「配列のリファレンス」を

-「ハッシュ」は「ハッシュのリファレンス」を意味しますので

-注意してください。)

 =head3 C<fetch>

-一行フェッチして配列に格納します。

+一行フェッチして配列のリファレンスに格納するにはC<fetch()>を使用します。

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

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

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

+        my $title  = $row->[0];

+        my $author = $row->[1];

     }

+whileループを使って、すべての行を取得することができます。

+

 =head3 C<fetch_first>

-一行だけフェッチして配列に格納します。

+一行だけフェッチして配列のリファレンスに格納するにはC<fetch_first()>

+を使用します。

     my $row = $result->fetch_first;

-フェッチが終わった後は、ステートメントハンドルからC<finish()>

-メソッドが呼び出されてそれ以上フェッチできなくなります。

+一行のフェッチが終わった後はそれ以上フェッチできなくなります。

+内部的には1行のフェッチが終わった後に

+ステートメントハンドルのC<finish()>が実行されます。

 =head3 C<fetch_multi>

-複数行をフェッチして配列の配列に格納します。

+複数行をフェッチして配列のリファレンスを要素に持つ

+配列のリファレンスに格納するにはC<fetch_multi()>を使用します。

-    while (my $rows = $result->fetch_multi(5)) {

-        my $first_author  = $rows->[0][0];

-        my $first_title   = $rows->[0][1];

-        my $second_author = $rows->[1][0];

-        my $second_value  = $rows->[1][1];

+    while (my $rows = $result->fetch_multi(2)) {

+        my $title0   = $rows->[0][0];

+        my $author0  = $rows->[0][1];

+        

+        my $title1   = $rows->[1][0];

+        my $author1  = $rows->[1][1];

     }

+引数には取り出したい行数を指定します。

+

+指定した行を格納した次のようなデータを取得できます。

+

+    [

+        ['Perl', 'Ken'],

+        ['Ruby', 'Mark']

+    ]

+

 =head3 C<fetch_all>

-すべての行をフェッチして配列の配列に格納します。

+すべての行をフェッチして配列のリファレンスを要素に持つ

+配列のリファレンスに格納するにはC<fetch_all()>を使用します。

     my $rows = $result->fetch_all;

+すべての行を格納した次のようなデータを取得できます。

+

+    [

+        ['Perl', 'Ken'],

+        ['Ruby', 'Mark']

+    ]

+

 =head3 C<fetch_hash>

-一行フェッチしてハッシュに格納します。

+一行フェッチしてハッシュのリファレンスに格納するにはC<fetch_hash()>を使用します。

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

         my $title  = $row->{title};

@@ -420,36 +425,64 @@ C<select()>メソッドの戻り値であるL<DBIx::Custom::Result>

 =head3 C<fetch_hash_first>

-一行だけフェッチしてハッシュに格納します。

+一行だけフェッチしてハッシュのリファレンスに格納するには

+C<fetch_hash_first()>を使用します。

     my $row = $result->fetch_hash_first;

-フェッチが終わった後は、ステートメントハンドルからC<finish()>

-メソッドが呼び出されてそれ以上フェッチできなくなります。

+一行のフェッチが終わった後はそれ以上フェッチできなくなります。

+内部的には1行のフェッチが終わった後に

+ステートメントハンドルのC<finish()>が実行されます。

 =head3 C<fetch_hash_multi>

-複数行をフェッチしてハッシュの配列に格納します。

+複数行をフェッチしてハッシュのリファレンスを要素に持つ

+配列のリファレンスに格納するにはC<fetch_hash_multi()>

+を使用します。

     while (my $rows = $result->fetch_hash_multi(5)) {

-        my $first_title   = $rows->[0]{title};

-        my $first_author  = $rows->[0]{author};

-        my $second_title  = $rows->[1]{title};

-        my $second_author = $rows->[1]{author};

+        my $title0   = $rows->[0]{title};

+        my $author0  = $rows->[0]{author};

+        my $title1  = $rows->[1]{title};

+        my $author1 = $rows->[1]{author};

     }

+引数には取り出したい行数を指定します。

+

+指定した行を格納した次のようなデータを取得できます。

+

+    [

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

+        {title => 'Ruby', author => 'Mark'}

+    ]

+

 =head3 C<fetch_all>

-すべての行をフェッチしてハッシュの配列に格納します。

+すべての行をフェッチしてハッシュのリファレンスを要素に持つ

+配列のリファレンスに格納するにはC<fetch_hash_all()>

+を使用します。

     my $rows = $result->fetch_hash_all;

-L<DBI>のステートメントハンドルに直接アクセスしたい場合は

-<sth>を使用します。

+すべての行を格納した次のようなデータを取得できます。

+

+    [

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

+        {title => 'Ruby', author => 'Mark'}

+    ]

+

+=head3 sth

+

+ステートメントハンドルに直接アクセスしたい場合は

+<sth>で取得することができます。

     my $sth = $result->sth;

-=head2 4. ハッシュパラメタバインド

+フェッチのパフォーマンスが用件を満たさないときには、

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

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

+

+=head2 4. タグ

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