Author: mjevans
Date: Tue Jun 8 02:28:36 2010
New Revision: 14121
Modified:
dbi/trunk/lib/DBD/File/Developers.pod
Log:
Corrected some typos and English
Modified: dbi/trunk/lib/DBD/File/Developers.pod
==============================================================================
--- dbi/trunk/lib/DBD/File/Developers.pod (original)
+++ dbi/trunk/lib/DBD/File/Developers.pod Tue Jun 8 02:28:36 2010
@@ -9,7 +9,7 @@
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.
+drivers. It supplements L<DBI::DBD>, which you should read first.
=head1 CLASSES
@@ -20,8 +20,8 @@
=item DBD::File::dr
-Driver package, contains the methods DBI called by the used indirectly via
-DBI interface:
+Driver package, contains the methods DBI calls indirectly via DBI
+interface:
DBI->connect ('DBI:DBM:', undef, undef, {})
@@ -36,9 +36,10 @@
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.
+Pure Perl DBI drivers derived from DBD::File do not usually need to
+override any of the methods provided through the DBD::XXX::dr package
+however if you need additional initialization in connect you may need
+to.
=item DBD::File::db
@@ -50,13 +51,13 @@
# 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 >>.
+DBD::File provides the typical methods required here. Developers who
+write DBI drivers based on DBD::File need 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:
+Contains the methods to deal with prepared statement handles:
$dbh = DBI->connect ("DBI::AnyData:", undef, undef, {});
$sth = $dbh->prepare ("select * from bar");
@@ -67,7 +68,7 @@
=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,
+based DBI drivers. Primarily the method C<< DBD::File::driver >> is invoked,
either directly from DBI when the driver is initialized or from the derived
class.
@@ -84,17 +85,18 @@
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.
+It is not necessary to implement your own driver method, as long as
+additional initialization (e.g. installing more private driver
+methods) is not required. You do not need to call C<< setup_driver >>
+as 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>).
+Driver package, contains the methods DBI calls 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:
+it is enough to do the basic initialization:
package DBD:XXX::dr;
@@ -114,40 +116,40 @@
=item ping
-Simply returns the content if the C<< Active >> attribute. Override when
-your driver needs more complicated actions here.
+Simply returns the content of 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
+C<< $sth >> - instance of the DBD:XXX::st. It is 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
+detected as a 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
+prefix (this is mandatory). If a requested attribute is detected as a 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.
+An example of a valid attributes list can be found in
+C<< DBD::File::db::init_valid_attributes >>.
=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<< sql_statement_version >> and (if not prohibited by a restrictive
C<< ${prefix}_valid_attrs >>) C<< ${prefix}_version >>.
This method is called at the end of the C<< connect () >> phase.
@@ -156,9 +158,10 @@
=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 >>).
+This method is called after the database handle is initialized as the
+first attribute initialization. When this method is complete, 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 >>,
@@ -176,14 +179,15 @@
DBD::File (e.g. DBI version, Perl version and of course, DBD::File version,
used sql handler including it's version, too).
-Overriding it to add some more version information about your module, (e.g.
+Override it to add more version information about your module, (e.g.
some kind of parser version in case of DBD::CSV, ...).
-C<< get_versions >> takes the C<< $dbh >> as first argument and an optionally
-second argument containing a table name. The second argument isn't evaluated
-in C<< DBD::File::db::get_versions >> - but might be done in future.
+C<< get_versions >> takes the C<< $dbh >> as the first argument and
+optionally a second argument containing a table name. The second
+argument is not evaluated in C<< DBD::File::db::get_versions >> - but
+might be in the future.
-See DBD::DBM::db::get_versions how to override it.
+See DBD::DBM::db::get_versions for an example.
=item get_file_meta
@@ -214,7 +218,7 @@
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.
+It is not recommended to override this method.
=item disconnect
@@ -240,13 +244,13 @@
=item commit
-Warns about useless call (if warnings enabled) and return.
+Warns about a useless call (if warnings enabled) and returns.
DBD::File is typically a driver which commits every action instantly when
executed.
=item rollback
-Warns about useless call (if warnings enabled) and return.
+Warns about a useless call (if warnings enabled) and returns.
DBD::File is typically a driver which commits every action instantly when
executed.
@@ -254,31 +258,30 @@
=head2 DBD::File::st
-Contains the methods to deal with once prepared statement handles:
+Contains the methods to deal with prepared statement handles:
=over 4
=item bind_param
-Common routine to bind placeholders to a statement for execution. It's
-dangerous to override this method without detailed knowledge about the
-DBD::File internal storage structure.
+Common routine to bind placeholders to a statement for execution. It
+is dangerous to override this method without detailed knowledge about
+the DBD::File internal storage structure.
=item execute
-Executes previously prepared statements (with placeholders, if any).
+Executes a previously prepared statement (with placeholders, if any).
=item finish
Finishes a statement handle, discards all buffered results. The prepared
-statement isn't discards to allow the statement can be executed multiple
-times.
+statement is not discarded so the statement can be executed again.
=item fetch
-Fetches next row from last execute results. This method may be rewritten
-in a later version and if it's overwritten in a derived class, the derived
-implementation shouldn't rely on the storage details.
+Fetches the next row from the result-set. This method may be rewritten
+in a later version and if it's overriden in a derived class, the
+derived implementation should not rely on the storage details.
=item fetchrow_arrayref
@@ -293,7 +296,7 @@
they can be fetched using this method, too. B<Note> that statement attributes
are not associated to any table used in this statement.
-This method usually requires being extended in a derived implementation.
+This method usually requires extending in a derived implementation.
See L<DBD::CSV> or L<DBD::DBM> for some example.
=item STORE
@@ -316,8 +319,8 @@
=item open_table
Implements the open_table method required by L<SQL::Statement> and
-L<DBI::SQL::Nano>. All real action for opening the file(s) belonging to the
-table is handled and parametrized in DBD::File::Table. Unless you intend
+L<DBI::SQL::Nano>. All the work for opening the file(s) belonging to the
+table is handled and parameterized in DBD::File::Table. Unless you intend
to add anything to the following implementation, an empty DBD::XXX::Statement
package satisfies DBD::File.
@@ -348,29 +351,29 @@
=item file2table
-This method tries to match between a file name and the fitting table name.
-It's called with a rudimentarily filled meta structure for the resulting
-table containg at least following attributes: C<< f_ext >>, C<< f_dir >>,
-C<< f_lockfile >> and C<< sql_identifier_case >>.
-
-It fills following attributes in the meta structure: C<< f_fqfn >>,
-C<< f_fqbn >>, C<< f_fqln >> and C<< table_name >> if the mapping job could
-be finished successfully. The table name is returned in this case - but
-I<undef> otherwise.
+This method tries to map a filename to the associated table
+name. It is called with a partly filled meta structure for the
+resulting table containing at least the following attributes:
+C<<f_ext >>, C<< f_dir >>, C<< f_lockfile >> and C<< sql_identifier_case>>.
+
+If a file/table map can be found then this method sets the C<< f_fqfn
+>>, C<< f_fqbn >>, C<< f_fqln >> and C<< table_name >> attributes in
+the meta structure. If a map cannot be found the table name will be
+undef.
=item bootstrap_table_meta
-Initializes a table meta structure rudimentarily. Can be safely overwritten
-in derived classed, as long as the C<< SUPER >> method is called at the end
-of the overwritten method.
+Initializes a table meta structure. Can be safely overwritten in a
+derived class, as long as the C<< SUPER >> method is called at the end
+of the overriden method.
It copies following attributes from the database into the table meta data
C<< f_dir >>, C<< f_ext >>, C<< f_encoding >>, C<< f_lock >>, C<< f_schema >>,
-C<< f_lockfile >> and C<< sql_identifier_case >> and make them sticky to the
-table this way.
+C<< f_lockfile >> and C<< sql_identifier_case >> and makes them sticky to the
+table.
-This method is called before it's tried to map between file name and table
-name to ensure right directory, extension etc. is used.
+This method should be called before you attempt to map between file
+name and table name to ensure right directory, extension etc. is used.
=item init_table_meta
@@ -380,23 +383,25 @@
=item get_table_meta
-Delivers the table meta data. If there are none for the required table, it's
-tried to initializes new ones. When it fails, nothing is returned. On
-success, the name of the table and the meta data structure is returned.
+Delivers the table meta data. If there are none for the required
+table, a new one is initialized. When it fails, nothing is
+returned. On success, the name of the table and the meta data
+structure is returned.
=item open_file
Is called to open the table's data file.
-Depending on the attributes set in table's meta data, following steps are
-done: unless C<< f_dontopen >> is set to a true value, C<< f_fqfn >> must
-contain the full qualified file name for the table to work on (file2table
-ensures this). The encoding in C<< f_encoding >> is applied if set and
-the file is opened. If C<< f_fqln >> (full qualified lock name) is set,
-this file is opened, too. Depending of the value in C<< f_lock >>, the
-appropriate lock is set on the opened data file or lock file, respectively.
+Depending on the attributes set in the table's meta data, the
+following steps are performed: unless C<< f_dontopen >> is set to a
+true value, C<< f_fqfn >> must contain the full qualified file name
+for the table to work on (file2table ensures this). The encoding in
+C<< f_encoding >> is applied if set and the file is opened. If
+C<<f_fqln >> (full qualified lock name) is set, this file is opened,
+too. Depending on the value in C<< f_lock >>, the appropriate lock is
+set on the opened data file or lock file.
-After this is done, a derived class might add more steps in an overwritten
+After this is done, a derived class might add more steps in an overriden
C<< open_file >> method.
=item new
@@ -407,25 +412,27 @@
2. open the data file
3. bless the table data structure using inherited constructor new
-It's not recommended to override the constructor of the table class.
-Find a reasonable place to add you extensions in one of above four methods.
+It is not recommended to override the constructor of the table class.
+Find a reasonable place to add you extensions in one of the above four
+methods.
=item drop
-Implements abstract table method for C<< DROP >> command. Discards table
-meta data after all files belonging to the table are closed and unlinked.
+Implements the abstract table method for the C<< DROP >>
+command. Discards table meta data after all files belonging to the
+table are closed and unlinked.
Overriding this method might be reasonable in very rare cases.
=item seek
-Implements abstract table method used when accessing the table from the
+Implements the abstract table method used when accessing the table from the
engine. C<< seek >> is called every time the engine uses dumb algorithms
for iterating over the table content.
=item truncate
-Implements abstract table method used when dumb table algorithms for
+Implements the abstract table method used when dumb table algorithms for
C<< UPDATE >> or C<< DELETE >> to truncate the table storage after last
written row.
@@ -433,7 +440,7 @@
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
+table's base class you have to override and a description of the table
meta information expected by the SQL engines.
=head1 AUTHOR
