more dob updates

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Table.pm

diff --git a/lib/DBIx/Class/Table.pm b/lib/DBIx/Class/Table.pm
index ba79341..e1bbe7d 100644 (file)
--- a/lib/DBIx/Class/Table.pm
+++ b/lib/DBIx/Class/Table.pm
@@ -4,8 +4,9 @@ use strict;
 use warnings;
 
 use DBIx::Class::ResultSet;
+use Data::Page;
 
-use base qw/Class::Data::Inheritable/;
+use base qw/DBIx::Class/;
 
 __PACKAGE__->mk_classdata('_columns' => {});
 
@@ -25,13 +26,11 @@ DBIx::Class::Table - Basic table methods
 
 =head1 DESCRIPTION
 
-This class is responsible for defining and doing basic operations on 
-L<DBIx::Class> objects.
+This class is responsible for defining and doing table-level operations on 
+L<DBIx::Class> classes.
 
 =head1 METHODS
 
-=over 4
-
 =cut
 
 sub _register_columns {
@@ -46,11 +45,11 @@ sub _mk_column_accessors {
   $class->mk_group_accessors('column' => @cols);
 }
 
-=item add_columns
+=head2 add_columns
 
   __PACKAGE__->add_columns(qw/col1 col2 col3/);
 
-Adds columns to the current package, and creates accessors for them
+Adds columns to the current class and creates accessors for them.
 
 =cut
 
@@ -60,7 +59,7 @@ sub add_columns {
   $class->_mk_column_accessors(@cols);
 }
 
-=item search_literal
+=head2 search_literal
 
   my @obj    = $class->search_literal($literal_where_cond, @bind);
   my $cursor = $class->search_literal($literal_where_cond, @bind);
@@ -75,7 +74,7 @@ sub search_literal {
   return $class->search(\$cond, $attrs);
 }
 
-=item count_literal
+=head2 count_literal
 
   my $count = $class->count_literal($literal_where_cond);
 
@@ -86,7 +85,7 @@ sub count_literal {
   return $class->search_literal(@_)->count;
 }
 
-=item count
+=head2 count
 
   my $count = $class->count({ foo => 3 });
 
@@ -97,11 +96,21 @@ sub count {
   return $class->search(@_)->count;
 }
 
-=item search 
+=head2 search 
 
-  my @obj    = $class->search({ foo => 3 });
+  my @obj    = $class->search({ foo => 3 }); # "... WHERE foo = 3"
   my $cursor = $class->search({ foo => 3 });
 
+To retrieve all rows, simply call C<search()> with no condition parameter,
+
+  my @all = $class->search(); # equivalent to search({})
+
+If you need to pass in additional attributes (see
+L<DBIx::Class::ResultSet/Attributes> for details) an empty hash indicates
+no condition,
+
+  my @all = $class->search({}, { cols => [qw/foo bar/] }); # "SELECT foo, bar FROM $class_table"
+
 =cut
 
 sub search {
@@ -112,9 +121,9 @@ sub search {
     $attrs = { %{ pop(@_) } };
   }
   $attrs->{where} = (@_ == 1 || ref $_[0] eq "HASH" ? shift: {@_});
-
+  
   my $rs = $class->resultset($attrs);
-
+  
   return (wantarray ? $rs->all : $rs);
 }
 
@@ -126,7 +135,7 @@ sub resultset {
   my $rs = $rs_class->new($class, @_);
 }
 
-=item search_like
+=head2 search_like
 
 Identical to search except defaults to 'LIKE' instead of '=' in condition
 
@@ -147,9 +156,11 @@ sub _select_columns {
   return keys %{$_[0]->_columns};
 }
 
-=item table
+=head2 table
 
   __PACKAGE__->table('tbl_name');
+  
+Gets or sets the table name.
 
 =cut
 
@@ -157,27 +168,61 @@ sub table {
   shift->_table_name(@_);
 }
 
-=item find_or_create
+=head2 find_or_create
 
   $class->find_or_create({ key => $val, ... });
 
 Searches for a record matching the search condition; if it doesn't find one,
-creates one and returns that instead
+creates one and returns that instead.
 
 =cut
 
 sub find_or_create {
   my $class    = shift;
   my $hash     = ref $_[0] eq "HASH" ? shift: {@_};
-  my ($exists) = $class->search($hash);
+  my $exists = $class->find($hash);
   return defined($exists) ? $exists : $class->create($hash);
 }
 
-sub columns { return keys %{shift->_columns}; }
+=head2 has_column                                                                
+                                                                                
+  if ($obj->has_column($col)) { ... }                                           
+                                                                                
+Returns 1 if the class has a column of this name, 0 otherwise.                  
+                                                                                
+=cut                                                                            
+
+sub has_column {
+  my ($self, $column) = @_;
+  return exists $self->_columns->{$column};
+}
 
-1;
+=head2 column_info                                                               
+                                                                                
+  my $info = $obj->column_info($col);                                           
+                                                                                
+Returns the column metadata hashref for a column.
+                                                                                
+=cut                                                                            
+
+sub column_info {
+  my ($self, $column) = @_;
+  die "No such column $column" unless exists $self->_columns->{$column};
+  return $self->_columns->{$column};
+}
+
+=head2 columns                                                                   
+                                                                                
+  my @column_names = $obj->columns;                                             
+                                                                                
+=cut                                                                            
 
-=back
+sub columns {
+  die "columns() is a read-only accessor, did you mean add_columns()?" if (@_ > 1);
+  return keys %{shift->_columns};
+}
+
+1;
 
 =head1 AUTHORS