Author: REHSACK
Date: Mon Dec 17 04:37:07 2012
New Revision: 15517
Modified:
dbi/branches/sqlengine/lib/DBD/File.pm
dbi/branches/sqlengine/lib/DBD/File/Developers.pod
dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine.pm
dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine/Developers.pod
Log:
- update basic documentation
- add f_meta support when $dbh->{ $drv_prefix . "meta" } is set
Modified: dbi/branches/sqlengine/lib/DBD/File.pm
==============================================================================
--- dbi/branches/sqlengine/lib/DBD/File.pm (original)
+++ dbi/branches/sqlengine/lib/DBD/File.pm Mon Dec 17 04:37:07 2012
@@ -188,28 +188,31 @@
push @{$dbh->{sql_init_order}{90}}, "f_meta";
- if(0) { # XXX remove block
# complete derived attributes, if required
(my $drv_class = $dbh->{ImplementorClass}) =~ s/::db$//;
my $drv_prefix = DBI->driver_prefix ($drv_class);
- my $valid_attrs = $drv_prefix . "valid_attrs";
- my $ro_attrs = $drv_prefix . "readonly_attrs";
+ if ( exists $dbh->{ $drv_prefix . "meta" } and
!$dbh->{sql_engine_in_gofer} ) {
+ my $attr = $dbh->{ $drv_prefix . "meta" };
+ defined $dbh->{f_valid_attrs}{f_meta}
+ and $dbh->{f_valid_attrs}{f_meta} = 1;
- my @comp_attrs = ();
-
- foreach my $comp_attr (@comp_attrs) {
- my $attr = $drv_prefix . $comp_attr;
- defined $dbh->{$valid_attrs} and !defined
$dbh->{$valid_attrs}{$attr} and
- $dbh->{$valid_attrs}{$attr} = 1;
- defined $dbh->{$ro_attrs} and !defined $dbh->{$ro_attrs}{$attr} and
- $dbh->{$ro_attrs}{$attr} = 1;
+ $dbh->{f_meta} = $dbh->{$attr};
}
- } # if 0
}
return $dbh;
} # init_default_attributes
+sub validate_FETCH_attr
+{
+ my ( $dbh, $attrib ) = @_;
+
+ $attrib eq "f_meta" and $dbh->{sql_engine_in_gofer} and $attrib =
"sql_meta";
+
+ return $dbh->SUPER::validate_FETCH_attr ($attrib);
+ } # validate_FETCH_attr
+
+
sub validate_STORE_attr
{
my ($dbh, $attrib, $value) = @_;
@@ -226,6 +229,8 @@
carp "'$value' doesn't look like a valid file extension
attribute\n";
}
+ $attrib eq "f_meta" and $dbh->{sql_engine_in_gofer} and $attrib =
"sql_meta";
+
return $dbh->SUPER::validate_STORE_attr ($attrib, $value);
} # validate_STORE_attr
@@ -1068,13 +1073,13 @@
$dbh = DBI->connect ("dbi:DBM:f_lockfile=.foo");
$dbh->{f_lockfile} = ".foo";
- $dbh->{f_meta}{qux}{f_lockfile} = ".foo";
+ $dbh->{dbm_tables}{qux}{f_lockfile} = ".foo";
If you wish to disable locking, set the C<f_lockfile> to C<0>.
$dbh = DBI->connect ("dbi:DBM:f_lockfile=0");
$dbh->{f_lockfile} = 0;
- $dbh->{f_meta}{qux}{f_lockfile} = 0;
+ $dbh->{dbm_tables}{qux}{f_lockfile} = 0;
=head4 f_encoding
@@ -1083,17 +1088,17 @@
=head4 f_meta
-Private data area which contains information about the tables this
-module handles. Table meta data might not be available until the
-table has been accessed for the first time e.g., by issuing a select
-on it however it is possible to pre-initialize attributes for each table
-you use.
+Private data area aliasing L<DBI::DBD::SqlEngine/sql_meta> which
+contains information about the tables this module handles. Table meta
+data might not be available until the table has been accessed for the
+first time e.g., by issuing a select on it however it is possible to
+pre-initialize attributes for each table you use.
DBD::File recognizes the (public) attributes C<f_ext>, C<f_dir>,
C<f_file>, C<f_encoding>, C<f_lock>, C<f_lockfile>, C<f_schema>,
-C<col_names>, C<table_name> and C<sql_identifier_case>. Be very careful
-when modifying attributes you do not know, the consequence might be a
-destroyed or corrupted table.
+in addition to the attributes L<DBI::DBD::SqlEngine/sql_meta> already
+supports. Be very careful when modifying attributes you do not know,
+the consequence might be a destroyed or corrupted table.
C<f_file> is an attribute applicable to table meta data only and you
will not find a corresponding attribute in the dbh. Whilst it may be
Modified: dbi/branches/sqlengine/lib/DBD/File/Developers.pod
==============================================================================
--- dbi/branches/sqlengine/lib/DBD/File/Developers.pod (original)
+++ dbi/branches/sqlengine/lib/DBD/File/Developers.pod Mon Dec 17 04:37:07 2012
@@ -65,7 +65,7 @@
sub bootstrap_table_meta { ... }
sub init_table_meta { ... }
sub table_meta_attr_changed { ... }
- sub open_file { ... }
+ sub open_data { ... }
sub fetch_row { ... }
sub push_row { ... }
Modified: dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine.pm
==============================================================================
--- dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine.pm (original)
+++ dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine.pm Mon Dec 17 04:37:07 2012
@@ -450,9 +450,9 @@
my @comp_attrs = qw(valid_attrs version readonly_attrs);
- if ( exists $dbh->{ $drv_prefix . "meta" } and
!$dbh->{sql_engine_in_gofer} )
+ if ( exists $dbh->{$drv_pfx_meta} and !$dbh->{sql_engine_in_gofer} )
{
- my $attr = $dbh->{ $drv_prefix . "meta" };
+ my $attr = $dbh->{$drv_pfx_meta};
defined $attr
and defined $dbh->{$valid_attrs}
and !defined $dbh->{$valid_attrs}{$attr}
@@ -533,7 +533,7 @@
# would force Gofer to serialize the tieing object including it's
# private $dbh reference used to do the driver function calls.
# This will result in nasty exceptions. So return a copy of the
- # f_meta structure instead, which is the source of for the compatibility
+ # sql_meta structure instead, which is the source of for the compatibility
# tie-hash. It's not as good as liked, but the best we can do in this
# situation.
if ( $dbh->{sql_engine_in_gofer} )
@@ -600,17 +600,7 @@
( my $drv_class = $dbh->{ImplementorClass} ) =~ s/::db$//;
my $drv_prefix = DBI->driver_prefix($drv_class);
- if ( exists $dbh->{ $drv_prefix . "meta" } )
- {
- my $attr = $dbh->{ $drv_prefix . "meta" };
- if ( $attrib eq $attr )
- {
- while ( my ( $k, $v ) = each %$value )
- {
- $dbh->{$attrib}{$k} = $v;
- }
- }
- }
+ exists $dbh->{ $drv_prefix . "meta" } and $attrib eq $dbh->{ $drv_prefix .
"meta" } and $attrib = "sql_meta";
return ( $attrib, $value );
}
@@ -660,7 +650,18 @@
and return $dbh->set_err( $DBI::stderr,
"attribute '$attrib' is readonly and must
not be modified" );
- $dbh->{$attrib} = $value;
+ if ( $attrib eq "sql_meta" )
+ {
+ while ( my ( $k, $v ) = each %$value )
+ {
+ $dbh->{$attrib}{$k} = $v;
+ }
+ }
+ else
+ {
+ $dbh->{$attrib} = $value;
+ }
+
return 1;
}
@@ -1822,6 +1823,37 @@
it's strongly recommended to set this flag before any statement is
executed (best place is connect attribute hash).
+=head4 sql_meta
+
+Private data area which contains information about the tables this
+module handles. Table meta data might not be available until the
+table has been accessed for the first time e.g., by issuing a select
+on it however it is possible to pre-initialize attributes for each table
+you use.
+
+DBI::DBD::SqlEngine recognizes the (public) attributes C<col_names>,
+C<table_name>, C<readonly>, C<sql_data_source> and C<sql_identifier_case>.
+Be very careful when modifying attributes you do not know, the consequence
+might be a destroyed or corrupted table.
+
+While C<sql_meta> is a private and readonly attribute (which means, you
+cannot modify it's values), derived drivers might provide restricted
+write access through another attribute. Well known accessors are
+C<csv_tables> for L<DBD::CSV>, C<ad_tables> for L<DBD::AnyData> and
+C<dbm_tables> for L<DBD::DBM>.
+
+=head4 sql_table_source
+
+Controls the class which will be used for fetching available tables.
+
+XXX See L</TableSource>
+
+=head4 sql_data_source
+
+Contains the class name to be used for opening tables.
+
+XXX See L</DataSource>
+
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
Modified: dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine/Developers.pod
==============================================================================
--- dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine/Developers.pod (original)
+++ dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine/Developers.pod Mon Dec 17
04:37:07 2012
@@ -54,6 +54,22 @@
@ISA = qw(DBI::DBD::SqlEngine::Table);
+ my %reset_on_modify = (
+ myd_abc => "myd_foo",
+ myd_mno => "myd_bar",
+ );
+ __PACKAGE__->register_reset_on_modify( \%reset_on_modify );
+ my %compat_map = (
+ abc => 'foo_abc',
+ xyz => 'foo_xyz',
+ );
+ __PACKAGE__->register_compat_map( \%compat_map );
+
+ sub bootstrap_table_meta { ... }
+ sub init_table_meta { ... }
+ sub table_meta_attr_changed { ... }
+ sub open_data { ... }
+
sub new { ... }
sub fetch_row { ... }
@@ -193,6 +209,17 @@
C<< $sth >> - instance of the DBD:XXX::st. It is neither required nor
recommended to override this method.
+=item validate_FETCH_attr
+
+Called by C<FETCH> to allow inherited drivers do their own attribute
+name validation. Calling convention is similar to C<FETCH> and the
+return value is the approved attribute name.
+
+ return $validated_attribute_name;
+
+In case of validation fails (eg. accessing private attribute or similar),
+C<validate_FETCH_attr> is permitted to throw an exception.
+
=item FETCH
Fetches an attribute of a DBI database object. Private handle attributes
@@ -208,6 +235,22 @@
attribute value is returned. So it's not possible to modify
C<f_valid_attrs> from outside of DBI::DBD::SqlEngine::db or a derived class.
+=item validate_STORE_attr
+
+Called by C<STORE> to allow inherited drivers do their own attribute
+name validation. Calling convention is similar to C<STORE> and the
+return value is the approved attribute name followed by the approved
+new value.
+
+ return ($validated_attribute_name, $validated_attribute_value);
+
+In case of validation fails (eg. accessing private attribute or similar),
+C<validate_STORE_attr> is permitted to throw an exception
+(C<DBI::DBD::SqlEngine::db::validate_STORE_attr> throws an exception when
+someone tries to assign value other than C<SQL_IC_UPPER .. SQL_IC_MIXED>
+to C<< $dbh->{sql_identifier_case} >> or
+C<< $dbh->{sql_quoted_identifier_case} >>).
+
=item STORE
Stores a database private attribute. Private handle attributes must have a
