[svn:dbi] r14091 - in dbi/trunk: . lib/DBD/File

Author: REHSACK
Date: Tue Jun  1 11:01:09 2010
New Revision: 14091

Added:
   dbi/trunk/lib/DBD/File/Developers.pod
Modified:
   dbi/trunk/MANIFEST

Log:
Adding developer documentation for DBD::File (first part)


Modified: dbi/trunk/MANIFEST
==============================================================================
--- dbi/trunk/MANIFEST	(original)
+++ dbi/trunk/MANIFEST	Tue Jun  1 11:01:09 2010
@@ -27,6 +27,8 @@
 lib/DBD/DBM.pm			A driver for DBM files (uses DBD::File)
 lib/DBD/ExampleP.pm		A very simple example Driver module
 lib/DBD/File.pm			A driver base class for simple drivers
+lib/DBD/File/Developers.pod	Developer documentation for DBD::File
+lib/DBD/File/Roadmap.pod	Roadmap for DBD::File and other Pure Perl DBD's
 lib/DBD/Gofer.pm                DBD::Gofer 'stateless proxy' driver
 lib/DBD/Gofer/Policy/Base.pm
 lib/DBD/Gofer/Policy/pedantic.pm    Safest and most transparent, but also slowest

Added: dbi/trunk/lib/DBD/File/Developers.pod
==============================================================================
--- (empty file)
+++ dbi/trunk/lib/DBD/File/Developers.pod	Tue Jun  1 11:01:09 2010
@@ -0,0 +1,297 @@
+=head1 NAME
+
+DBD::File::Developers - Developers documentation for DBD::File
+
+=head1 SYNOPSIS
+
+  perldoc DBD::File::Developers
+
+  perldoc DBD::File::Roadmap
+
+This document describes how DBD developers can write DBD::File based DBI
+drivers. It supplements L<DBI::DBD>, which should had been read before.
+
+=head1 CLASSES
+
+Each DBI driver must provide a package global C<< driver >> method and
+three DBI related classes:
+
+=over 4
+
+=item DBD::File::dr
+
+Driver package, contains the methods DBI called by the used indirectly via
+DBI interface:
+
+  DBI->connect ('DBI:DBM:', undef, undef, {})
+
+  # invokes
+  package DBD::DBM::dr;
+  @DBD::DBM::dr::ISA = qw(DBD::File::dr);
+
+  sub connect ($$;$$$)
+  {
+      ...
+  }
+
+Similar for C<< data_sources () >> and C<< disconnect_all() >>.
+
+Usually Pure Perl DBI drivers derived from DBD::File don't need to override
+any of the methods provided through the DBD::XXX::dr package, as long no
+additional initialization is needed on connect.
+
+=item DBD::File::db
+
+Contains the methods which are called through DBI database handles
+(C<< $dbh >>).
+
+  my $dbh = DBI->connect ('DBI:CSV:', unef, undef, { f_ext => '.csv/r' });
+  $dbh->prepare ("select * from foo");
+  # returns the f_encoding setting for table foo
+  $dbh->csv_get_meta ("foo", "f_encoding");
+
+DBD::File provides the typical methods required here. Developers who write
+DBI drivers based on DBD::File are enforced to override the methods
+C<< set_versions >> and C<< init_valid_attributes >>.
+
+=item DBD::File::st
+
+Contains the methods to deal with once prepared statement handles:
+
+  $dbh = DBI->connect ("DBI::AnyData:", undef, undef, {});
+  $sth = $dbh->prepare ("select * from bar");
+  $sth->execute () or die $sth->errstr;
+
+=back
+
+=head2 DBD::File
+
+This is the main package containing the routines to initialize DBD::File
+based DBI driver. Primarily the method C<< DBD::File::driver >> is invoked,
+either directly from DBI when the driver is initialized or from the derived
+class.
+
+  package DBD::DBM;
+
+  use base qw( DBD::File );
+
+  sub driver
+  {
+      my ( $class, $attr ) = @_;
+      ...
+      my $drh = $class->SUPER::driver( $attr );
+      ...
+      return $drh;
+  }
+
+It's not necessary to implement an own driver method, as long as additional
+initialization must be done (e.g. installing more private driver methods).
+Caling C<< setup_driver >> isn't needed, DBD::File takes care of it.
+
+=head2 DBD::File::dr
+
+Driver package, contains the methods DBI called by the used indirectly via
+DBI interface (see L<DBI/DBI Class Methods>).
+
+DBD::File based DBI drivers usually do not need to implement anything here,
+it's enough to do the basic initialization:
+
+  package DBD:XXX::dr;
+
+  @DBD::XXX::dr::ISA = qw (DBD::File::dr);
+  $DBD::XXX::dr::imp_data_size     = 0;
+  $DBD::XXX::dr::data_sources_attr = undef;
+  $DBD::XXX::ATTRIBUTION = "DBD::XXX $DBD::XXX::VERSION by Hans Mustermann";
+
+=head2 DBD::File::db
+
+This package defines the database methods, which are called via the DBI
+database handle C<< $dbh >>.
+
+Methods provided by DBD::File:
+
+=over 4
+
+=item ping
+
+Simply returns the content if the C<< Active >> attribute. Override when
+your driver needs more complicated actions here.
+
+=item prepare
+
+Prepares a new SQL statement to execute. Returns a statement handle,
+C<< $sth >> - instance of the DBD:XXX::st. It's neither required nor
+recommended to override this method.
+
+=item FETCH
+
+Fetches an attribute of a DBI database object. Private handle attributes
+must have a prefix (this is mandatory). If a requested attribute is
+detected as private attribute without a valid prefix, the driver prefix
+is added. If the database handle has an attribute ${prefix}_valid_attrs -
+for attribute names which are not listed in that hash, this method croaks.
+
+=item STORE
+
+Stores a database private attribute. Private handle attributes must have a
+prefix (this is mandatory). If a requested attribute is detected as private
+attribute without a valid prefix, the driver prefix is added. If the
+database handle has an attribute ${prefix}_valid_attrs - for attribute
+names which are not listed in that hash, this method croaks. If the
+database handle has an attribute ${prefix}_readonly_attrs, only attributes
+which are not listed there can be stored (once they are initialized).
+
+Take a look into C<< DBD::File::db::init_valid_attributes >> to see how
+such lists look like.
+
+=item set_versions
+
+This method sets the attributes C<< f_version >>, C<< sql_nano_version >>,
+C<< sql_statement_version >> and (if not prohibited through restrictive
+C<< ${prefix}_valid_attrs >>) C<< ${prefix}_version >>.
+
+This method is called at the end of the C<< connect () >> phase.
+
+When overriding this method, do not forget to invoke the superior one.
+
+=item init_valid_attributes
+
+This method is called after the database handle is initialized as the first
+attribute initialization. When this method is done, default values for some
+attributes are set (e.g. for C<< f_dir >>, C<< sql_identifier_case >>).
+
+C<< DBD::File::db::init_valid_attributes >> initializes the attributes
+C<< f_valid_attrs >>, C<< sql_valid_attrs >>, C<< f_readonly_attrs >>,
+C<< sql_readonly_attrs >> and C<< sql_handler >>.
+
+When overriding this method, do not forget to invoke the superior one.
+
+=item sql_parser_object
+
+Delivers an L<SQL::Parser> instance, when C<< sql_handler >> is set to
+"SQL::Statement". The parser instance is stored in C<< sql_parser_object >>.
+
+It's not recommended to override this method.
+
+=item disconnect
+
+Disconnects from a database. All local table information are discarded and
+the attribute C<< Active >> is set to 0.
+
+=item type_info_all
+
+Delivers the information about all supported types by DBD::File.
+
+=item table_info
+
+Return a statement handle which is prepared to deliver information about
+all known tables.
+
+=item list_tables
+
+Returns a list of all known table names.
+
+=item quote
+
+Quotes a string for use it in SQL statements.
+
+=item commit
+
+Warns about useless call (if warnings enabled) and return.
+DBD::File is typically a driver which commits every action instantly when
+executed.
+
+=item rollback
+
+Warns about useless call (if warnings enabled) and return.
+DBD::File is typically a driver which commits every action instantly when
+executed.
+
+=back
+
+=head2 DBD::File::st
+
+Contains the methods to deal with once prepared statement handles:
+
+=over 4
+
+=item bind_param
+
+=item execute
+
+=item finish
+
+=item fetch
+
+=item fetchrow_arrayref
+
+=item FETCH
+
+=item STORE
+
+=item rows
+
+=back
+
+=head2 DBD::File::Statement
+
+Derives from DBI::SQL::Nano::Statement to provide following method:
+
+=over 4
+
+=item open_table
+
+=back
+
+=head2 DBD::File::Table
+
+Derives from DBI::SQL::Nano::Table and provides physical file access for
+the table data which are stored in the files.
+
+=over 4
+
+=item file2table
+
+=item bootstrap_table_meta
+
+=item init_table_meta
+
+=item get_table_meta
+
+=item open_file
+
+=item new
+
+=item drop
+
+=item seek
+
+=item truncate
+
+=back
+
+You should consult the documentation of C<< SQL::Eval::Table >> (see
+L<SQL::Eval>) to get more information about the abstract methods of the
+table's base class you have to overwrite and a description of the table
+meta information expected by the SQL engines.
+
+=head1 AUTHOR
+
+The module DBD::File is currently maintained by
+
+H.Merijn Brand < h.m.brand at xs4all.nl > and
+Jens Rehsack  < rehsack at googlemail.com >
+
+The original author is Jochen Wiedmann.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (C) 2010 by H.Merijn Brand & Jens Rehsack
+
+All rights reserved.
+
+You may freely distribute and/or modify this module under the terms of
+either the GNU General Public License (GPL) or the Artistic License, as
+specified in the Perl README file.
+
+=cut