From: Nigel Metheringham Date: Wed, 31 May 2006 21:58:16 +0000 (+0000) Subject: POD::Coverage additions X-Git-Tag: v0.07002~75^2~144 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=9b83fccd091065fcebbb6fb6fb7bf2c2da38ffe2;p=dbsrgits%2FDBIx-Class.git POD::Coverage additions --- diff --git a/Changes b/Changes index 8ef37bf..bfa7693 100644 --- a/Changes +++ b/Changes @@ -1,5 +1,8 @@ Revision history for DBIx::Class +0.06999_02 sometime? + - Fixed up POD::Coverage tests, filled in some POD holes + 0.06999_01 2006-05-28 17:19:30 - add automatic naming of unique constraints - marked DB.pm as deprecated and noted it will be removed by 1.0 diff --git a/lib/DBIx/Class/InflateColumn/DateTime.pm b/lib/DBIx/Class/InflateColumn/DateTime.pm index 24f9e48..f5feb95 100644 --- a/lib/DBIx/Class/InflateColumn/DateTime.pm +++ b/lib/DBIx/Class/InflateColumn/DateTime.pm @@ -37,6 +37,14 @@ __PACKAGE__->load_components(qw/InflateColumn/); __PACKAGE__->mk_group_accessors('simple' => '__datetime_parser'); +=head2 register_column + +Chains with the L method, and sets +up datetime columns appropriately. This would not normally be +directly called by end users. + +=cut + sub register_column { my ($self, $column, $info, @rest) = @_; $self->next::method($column, $info, @rest); diff --git a/lib/DBIx/Class/PK.pm b/lib/DBIx/Class/PK.pm index d093d93..9895edb 100644 --- a/lib/DBIx/Class/PK.pm +++ b/lib/DBIx/Class/PK.pm @@ -91,6 +91,16 @@ sub _create_ID { map { $_ . '=' . $vals{$_} } sort keys %vals; } +=head2 ident_condition + + my $cond = $result_source->ident_condition(); + + my $cond = $result_source->ident_condition('alias'); + +Produces a condition hash to locate a row based on the primary key(s). + +=cut + sub ident_condition { my ($self, $alias) = @_; my %cond; diff --git a/lib/DBIx/Class/Relationship/BelongsTo.pm b/lib/DBIx/Class/Relationship/BelongsTo.pm index 8c8ceaa..e32dd6d 100644 --- a/lib/DBIx/Class/Relationship/BelongsTo.pm +++ b/lib/DBIx/Class/Relationship/BelongsTo.pm @@ -1,4 +1,8 @@ -package DBIx::Class::Relationship::BelongsTo; +package # hide from PAUSE + DBIx::Class::Relationship::BelongsTo; + +# Documentation for these methods can be found in +# DBIx::Class::Relationship use strict; use warnings; diff --git a/lib/DBIx/Class/ResultSetManager.pm b/lib/DBIx/Class/ResultSetManager.pm index f5a62b4..46aa406 100644 --- a/lib/DBIx/Class/ResultSetManager.pm +++ b/lib/DBIx/Class/ResultSetManager.pm @@ -6,15 +6,15 @@ use Class::Inspector; =head1 NAME - DBIx::Class::ResultSetManager - helpful methods for managing - resultset classes (EXPERIMENTAL) +DBIx::Class::ResultSetManager - helpful methods for managing resultset +classes (EXPERIMENTAL) =head1 SYNOPSIS # in a table class __PACKAGE__->load_components(qw/ResultSetManager Core/); # note order! __PACKAGE__->load_resultset_components(qw/AlwaysRS/); - + # will be removed from the table class and inserted into a # table-specific resultset class sub search_by_year_desc : ResultSet { @@ -45,6 +45,17 @@ __PACKAGE__->mk_classdata($_) __PACKAGE__->base_resultset_class('DBIx::Class::ResultSet'); __PACKAGE__->table_resultset_class_suffix('::_resultset'); +=head2 table + +Stacks on top of the normal L C method. Any +methods tagged with the C attribute will be moved into a +table-specific resultset class (by default called +C, but configurable via +C). The magic for this is done within +this C<< __PACKAGE__->table >> call. + +=cut + sub table { my ($self,@rest) = @_; my $ret = $self->next::method(@rest); @@ -55,6 +66,18 @@ sub table { return $ret; } +=head2 load_resultset_components + + # in a table class + __PACKAGE__->load_components(qw/ResultSetManager Core/); # note order! + __PACKAGE__->load_resultset_components(qw/AlwaysRS/); + +C loads components in addition to +C (or whatever you set as +C). + +=cut + sub load_resultset_components { my ($self,@comp) = @_; my $resultset_class = $self->_setup_resultset_class; @@ -65,7 +88,7 @@ sub _register_attributes { my $self = shift; my $cache = $self->_attr_cache; return if keys %$cache == 0; - + foreach my $meth (@{Class::Inspector->methods($self) || []}) { my $attrs = $cache->{$self->can($meth)}; next unless $attrs; diff --git a/lib/DBIx/Class/Row.pm b/lib/DBIx/Class/Row.pm index 0752589..3efe418 100644 --- a/lib/DBIx/Class/Row.pm +++ b/lib/DBIx/Class/Row.pm @@ -170,6 +170,17 @@ sub get_column { return undef; } +=head2 has_column_loaded + + if ( $obj->has_column_loaded($col) ) { + print "$col has been loaded from db"; + } + +Returns a true value if the column value has been loaded from the +database (or set locally). + +=cut + sub has_column_loaded { my ($self, $column) = @_; $self->throw_exception( "Can't call has_column data as class method" ) unless ref $self; @@ -350,6 +361,12 @@ sub inflate_result { Updates the object if it's already in the db, else inserts it. +=head2 insert_or_update + + $obj->insert_or_update + +Alias for L + =cut *insert_or_update = \&update_or_insert; @@ -363,6 +380,10 @@ sub update_or_insert { my @changed_col_names = $obj->is_changed(); if ($obj->is_changed()) { ... } +In array context returns a list of columns with uncommited changes, or +in scalar context returns a true value if there are uncommitted +changes. + =cut sub is_changed { @@ -373,6 +394,8 @@ sub is_changed { if ($obj->is_column_changed('col')) { ... } +Returns a true value if the column has uncommitted changes. + =cut sub is_column_changed { @@ -382,19 +405,21 @@ sub is_column_changed { =head2 result_source - Accessor to the ResultSource this object was created from + my $resultsource = $object->result_source; -=head2 register_column +Accessor to the ResultSource this object was created from -=over 4 +=head2 register_column -=item Arguments: $column, $column_info + $column_info = { .... }; + $class->register_column($column_name, $column_info); -=back +Registers a column on the class. If the column_info has an 'accessor' +key, creates an accessor named after the value if defined; if there is +no such key, creates an accessor with the same name as the column - Registers a column on the class. If the column_info has an 'accessor' key, - creates an accessor named after the value if defined; if there is no such - key, creates an accessor with the same name as the column +The column_info attributes are described in +L =cut diff --git a/lib/DBIx/Class/Schema.pm b/lib/DBIx/Class/Schema.pm index a38572c..8c7eac1 100644 --- a/lib/DBIx/Class/Schema.pm +++ b/lib/DBIx/Class/Schema.pm @@ -731,6 +731,15 @@ sub create_ddl_dir $self->storage->create_ddl_dir($self, @_); } +=head2 ddl_filename (EXPERIMENTAL) + + my $filename = $table->ddl_filename($type, $dir, $version) + +Creates a filename for a SQL file based on the table class name. Not +intended for direct end user use. + +=cut + sub ddl_filename { my ($self, $type, $dir, $version) = @_; diff --git a/lib/DBIx/Class/Serialize/Storable.pm b/lib/DBIx/Class/Serialize/Storable.pm index b3ac604..7ccd2b0 100644 --- a/lib/DBIx/Class/Serialize/Storable.pm +++ b/lib/DBIx/Class/Serialize/Storable.pm @@ -29,7 +29,7 @@ __END__ # in a table class definition __PACKAGE__->load_components(qw/Serialize::Storable/); - + # meanwhile, in a nearby piece of code my $cd = $schema->resultset('CD')->find(12); # if the cache uses Storable, this will work automatically @@ -41,6 +41,22 @@ This component adds hooks for Storable so that row objects can be serialized. It assumes that your row object class (C) is the same as your table class, which is the normal situation. +=head1 HOOKS + +The following hooks are defined for L - see the +documentation for L for detailed information on these +hooks. + +=head2 STORABLE_freeze + +The serializing hook, called on the object during serialization. It +can be inherited, or defined in the class itself, like any other +method. + +=head2 STORABLE_thaw + +The deserializing hook called on the object during deserialization. + =head1 AUTHORS David Kamholz diff --git a/lib/DBIx/Class/Storage/DBI.pm b/lib/DBIx/Class/Storage/DBI.pm index 7802921..b7f1198 100644 --- a/lib/DBIx/Class/Storage/DBI.pm +++ b/lib/DBIx/Class/Storage/DBI.pm @@ -235,6 +235,10 @@ __PACKAGE__->mk_group_accessors('simple' => qw/_connect_info _dbh _sql_maker _conn_pid _conn_tid debug debugobj cursor on_connect_do transaction_depth/); +=head2 new + +=cut + sub new { my $new = bless({}, ref $_[0] || $_[0]); $new->cursor("DBIx::Class::Storage::DBI::Cursor"); @@ -255,6 +259,12 @@ sub new { return $new; } +=head2 throw_exception + +Throws an exception - croaks. + +=cut + sub throw_exception { my ($self, $msg) = @_; croak($msg); @@ -362,6 +372,13 @@ sub debugcb { } } +=head2 disconnect + +Disconnect the L handle, performing a rollback first if the +database is not in C mode. + +=cut + sub disconnect { my ($self) = @_; @@ -372,8 +389,14 @@ sub disconnect { } } -sub connected { - my ($self) = @_; +=head2 connected + +Check if the L handle is connected. Returns true if the handle +is connected. + +=cut + +sub connected { my ($self) = @_; if(my $dbh = $self->_dbh) { if(defined $self->_conn_tid && $self->_conn_tid != threads->tid) { @@ -391,6 +414,13 @@ sub connected { return 0; } +=head2 ensure_connected + +Check whether the database handle is connected - if not then make a +connection. + +=cut + sub ensure_connected { my ($self) = @_; @@ -418,6 +448,13 @@ sub _sql_maker_args { return ( limit_dialect => $self->dbh ); } +=head2 sql_maker + +Returns a C object - normally an object of class +C. + +=cut + sub sql_maker { my ($self) = @_; unless ($self->_sql_maker) { @@ -673,12 +710,25 @@ sub _select { return $self->_execute(@args); } +=head2 select + +Handle a SQL select statement. + +=cut + sub select { my $self = shift; my ($ident, $select, $condition, $attrs) = @_; return $self->cursor->new($self, \@_, $attrs); } +=head2 select_single + +Performs a select, fetch and return of data - handles a single row +only. + +=cut + # Need to call finish() to work round broken DBDs sub select_single { @@ -689,6 +739,12 @@ sub select_single { return @row; } +=head2 sth + +Returns a L sth (statement handle) for the supplied SQL. + +=cut + sub sth { my ($self, $sql) = @_; # 3 is the if_active parameter which avoids active sth re-use @@ -760,6 +816,12 @@ sub columns_info_for { return \%result; } +=head2 last_insert_id + +Return the row id of the last insert. + +=cut + sub last_insert_id { my ($self, $row) = @_; @@ -767,8 +829,30 @@ sub last_insert_id { } +=head2 sqlt_type + +Returns the database driver name. + +=cut + sub sqlt_type { shift->dbh->{Driver}->{Name} } +=head2 create_ddl_dir (EXPERIMENTAL) + +=over 4 + +=item Arguments: $schema \@databases, $version, $directory, $sqlt_args + +=back + +Creates an SQL file based on the Schema, for each of the specified +database types, in the given directory. + +Note that this feature is currently EXPERIMENTAL and may not work correctly +across all databases, or fully handle complex relationships. + +=cut + sub create_ddl_dir { my ($self, $schema, $databases, $version, $dir, $sqltargs) = @_; @@ -821,6 +905,13 @@ sub create_ddl_dir } +=head2 deployment_statements + +Create the statements for L and +L. + +=cut + sub deployment_statements { my ($self, $schema, $type, $version, $dir, $sqltargs) = @_; $type ||= $self->sqlt_type; @@ -855,6 +946,14 @@ sub deployment_statements { } +=head2 deploy + +Sends the appropriate statements to create or modify tables to the +db. This would normally be called through +L. + +=cut + sub deploy { my ($self, $schema, $type, $sqltargs) = @_; foreach my $statement ( $self->deployment_statements($schema, $type, undef, undef, $sqltargs) ) { @@ -871,13 +970,32 @@ sub deploy { } } +=head2 datetime_parser + +Returns the datetime parser class + +=cut + sub datetime_parser { my $self = shift; return $self->{datetime_parser} ||= $self->build_datetime_parser(@_); } +=head2 datetime_parser_type + +Defines (returns) the datetime parser class - currently hardwired to +L + +=cut + sub datetime_parser_type { "DateTime::Format::MySQL"; } +=head2 build_datetime_parser + +See L + +=cut + sub build_datetime_parser { my $self = shift; my $type = $self->datetime_parser_type(@_); @@ -890,6 +1008,32 @@ sub DESTROY { shift->disconnect } 1; +=head1 SQL METHODS + +The module defines a set of methods within the DBIC::SQL::Abstract +namespace. These build on L to provide the +SQL query functions. + +The following methods are extended:- + +=over 4 + +=item delete + +=item insert + +=item select + +=item update + +=item limit_dialect + +=item quote_char + +=item name_sep + +=back + =head1 ENVIRONMENT VARIABLES =head2 DBIX_CLASS_STORAGE_DBI_DEBUG diff --git a/lib/DBIx/Class/Validation.pm b/lib/DBIx/Class/Validation.pm index 4592a89..24a144a 100644 --- a/lib/DBIx/Class/Validation.pm +++ b/lib/DBIx/Class/Validation.pm @@ -141,6 +141,18 @@ is for auto-validation to be on. Defaults to on. +=head1 EXTENDED METHODS + +The following methods are extended by this module:- + +=over 4 + +=item insert + +=item update + +=back + =head1 AUTHOR Aran C. Deltac diff --git a/t/03podcoverage.t.disabled b/t/03podcoverage.t.disabled index 688b529..77460de 100644 --- a/t/03podcoverage.t.disabled +++ b/t/03podcoverage.t.disabled @@ -7,6 +7,15 @@ plan skip_all => 'set TEST_POD to enable this test' unless $ENV{TEST_POD}; my @modules = sort { $a cmp $b } (all_modules()); plan tests => scalar(@modules); +# Since this is about checking documentation, a little documentation +# of what this is doing might be in order... +# The exceptions structure below is a hash keyed by the module +# name. The value for each is a hash, which contains one or more +# (although currently more than one makes no sense) of the following +# things:- +# skip => a true value means this module is not checked +# ignore => array ref containing list of methods which +# do not need to be documented. my $exceptions = { 'DBIx::Class' => { ignore => [ @@ -15,9 +24,52 @@ my $exceptions = { mk_classdata/ ] }, - 'DBIx::Class::ResultSetProxy' => { skip => 1 }, - 'DBIx::Class::ResultSourceProxy' => { skip => 1 }, - 'DBIx::Class::Componentised' => { skip => 1 }, + 'DBIx::Class::CDBICompat::AccessorMapping' => { skip => 1 }, + 'DBIx::Class::CDBICompat::AttributeAPI' => { skip => 1 }, + 'DBIx::Class::CDBICompat::AutoUpdate' => { skip => 1 }, + 'DBIx::Class::CDBICompat::ColumnCase' => { skip => 1 }, + 'DBIx::Class::CDBICompat::ColumnGroups' => { skip => 1 }, + 'DBIx::Class::CDBICompat::Constraints' => { skip => 1 }, + 'DBIx::Class::CDBICompat::Constructor' => { skip => 1 }, + 'DBIx::Class::CDBICompat::DestroyWarning' => { skip => 1 }, + 'DBIx::Class::CDBICompat::GetSet' => { skip => 1 }, + 'DBIx::Class::CDBICompat::HasA' => { skip => 1 }, + 'DBIx::Class::CDBICompat::HasMany' => { skip => 1 }, + 'DBIx::Class::CDBICompat::ImaDBI' => { skip => 1 }, + 'DBIx::Class::CDBICompat::LazyLoading' => { skip => 1 }, + 'DBIx::Class::CDBICompat::LiveObjectIndex' => { skip => 1 }, + 'DBIx::Class::CDBICompat::MightHave' => { skip => 1 }, + 'DBIx::Class::CDBICompat::ObjIndexStubs' => { skip => 1 }, + 'DBIx::Class::CDBICompat::Pager' => { skip => 1 }, + 'DBIx::Class::CDBICompat::ReadOnly' => { skip => 1 }, + 'DBIx::Class::CDBICompat::Retrieve' => { skip => 1 }, + 'DBIx::Class::CDBICompat::Stringify' => { skip => 1 }, + 'DBIx::Class::CDBICompat::TempColumns' => { skip => 1 }, + 'DBIx::Class::CDBICompat::Triggers' => { skip => 1 }, + 'DBIx::Class::ClassResolver::PassThrough' => { skip => 1 }, + 'DBIx::Class::Componentised' => { skip => 1 }, + 'DBIx::Class::Relationship::Accessor' => { skip => 1 }, + 'DBIx::Class::Relationship::BelongsTo' => { skip => 1 }, + 'DBIx::Class::Relationship::CascadeActions' => { skip => 1 }, + 'DBIx::Class::Relationship::HasMany' => { skip => 1 }, + 'DBIx::Class::Relationship::HasOne' => { skip => 1 }, + 'DBIx::Class::Relationship::Helpers' => { skip => 1 }, + 'DBIx::Class::Relationship::ManyToMany' => { skip => 1 }, + 'DBIx::Class::Relationship::ProxyMethods' => { skip => 1 }, + 'DBIx::Class::ResultSetProxy' => { skip => 1 }, + 'DBIx::Class::ResultSourceProxy' => { skip => 1 }, + 'DBIx::Class::Storage' => { skip => 1 }, + 'DBIx::Class::Storage::DBI::DB2' => { skip => 1 }, + 'DBIx::Class::Storage::DBI::MSSQL' => { skip => 1 }, + 'DBIx::Class::Storage::DBI::MultiDistinctEmulation' => { skip => 1 }, + 'DBIx::Class::Storage::DBI::ODBC400' => { skip => 1 }, + 'DBIx::Class::Storage::DBI::ODBC::DB2_400_SQL' => { skip => 1 }, + 'DBIx::Class::Storage::DBI::Oracle' => { skip => 1 }, + 'DBIx::Class::Storage::DBI::Pg' => { skip => 1 }, + 'DBIx::Class::Storage::DBI::SQLite' => { skip => 1 }, + 'DBIx::Class::Storage::DBI::mysql' => { skip => 1 }, + 'SQL::Translator::Parser::DBIx::Class' => { skip => 1 }, + 'SQL::Translator::Producer::DBIx::Class::File' => { skip => 1 }, }; foreach my $module (@modules) {