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
lmpx.com only provides a reader for public news (NNTP) servers. It is not
affiliated with the servers or forums shown here and is not responsible for
the content of articles, which is written by their respective authors.