Merge 'trunk' into 'DBIx-Class-C3'
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Table.pm
1 package DBIx::Class::Table;
2
3 use strict;
4 use warnings;
5
6 use DBIx::Class::ResultSet;
7 use Data::Page;
8
9 use base qw/DBIx::Class/;
10
11 __PACKAGE__->mk_classdata('_columns' => {});
12
13 __PACKAGE__->mk_classdata('_table_name');
14
15 __PACKAGE__->mk_classdata('table_alias'); # FIXME: Doesn't actually do anything yet!
16
17 __PACKAGE__->mk_classdata('_resultset_class' => 'DBIx::Class::ResultSet');
18
19 sub iterator_class { shift->_resultset_class(@_) }
20
21 =head1 NAME 
22
23 DBIx::Class::Table - Basic table methods
24
25 =head1 SYNOPSIS
26
27 =head1 DESCRIPTION
28
29 This class is responsible for defining and doing basic operations on 
30 L<DBIx::Class> objects.
31
32 =head1 METHODS
33
34 =over 4
35
36 =cut
37
38 sub _register_columns {
39   my ($class, @cols) = @_;
40   my $names = { %{$class->_columns} };
41   $names->{$_} ||= {} for @cols;
42   $class->_columns($names); 
43 }
44
45 sub _mk_column_accessors {
46   my ($class, @cols) = @_;
47   $class->mk_group_accessors('column' => @cols);
48 }
49
50 =item add_columns
51
52   __PACKAGE__->add_columns(qw/col1 col2 col3/);
53
54 Adds columns to the current package, and creates accessors for them
55
56 =cut
57
58 sub add_columns {
59   my ($class, @cols) = @_;
60   $class->_register_columns(@cols);
61   $class->_mk_column_accessors(@cols);
62 }
63
64 =item search_literal
65
66   my @obj    = $class->search_literal($literal_where_cond, @bind);
67   my $cursor = $class->search_literal($literal_where_cond, @bind);
68
69 =cut
70
71 sub search_literal {
72   my ($class, $cond, @vals) = @_;
73   $cond =~ s/^\s*WHERE//i;
74   my $attrs = (ref $vals[$#vals] eq 'HASH' ? { %{ pop(@vals) } } : {});
75   $attrs->{bind} = \@vals;
76   return $class->search(\$cond, $attrs);
77 }
78
79 =item count_literal
80
81   my $count = $class->count_literal($literal_where_cond);
82
83 =cut
84
85 sub count_literal {
86   my $class = shift;
87   return $class->search_literal(@_)->count;
88 }
89
90 =item count
91
92   my $count = $class->count({ foo => 3 });
93
94 =cut
95
96 sub count {
97   my $class = shift;
98   return $class->search(@_)->count;
99 }
100
101 =item search 
102
103   my @obj    = $class->search({ foo => 3 }); # "... WHERE foo = 3"
104   my $cursor = $class->search({ foo => 3 });
105
106 To retrieve all rows, simply call C<search()> with no condition parameter,
107
108   my @all = $class->search(); # equivalent to search({})
109
110 If you need to pass in additional attributes (see
111 L<DBIx::Class::ResultSet/Attributes> for details) an empty hash indicates
112 no condition,
113
114   my @all = $class->search({}, { cols => [qw/foo bar/] }); # "SELECT foo, bar FROM $class_table"
115
116 =cut
117
118 sub search {
119   my $class = shift;
120   #warn "@_";
121   my $attrs = { };
122   if (@_ > 1 && ref $_[$#_] eq 'HASH') {
123     $attrs = { %{ pop(@_) } };
124   }
125   $attrs->{where} = (@_ == 1 || ref $_[0] eq "HASH" ? shift: {@_});
126   
127   my $rs = $class->resultset($attrs);
128   
129   return (wantarray ? $rs->all : $rs);
130 }
131
132 sub resultset {
133   my $class = shift;
134
135   my $rs_class = $class->_resultset_class;
136   eval "use $rs_class;";
137   my $rs = $rs_class->new($class, @_);
138 }
139
140 =item search_like
141
142 Identical to search except defaults to 'LIKE' instead of '=' in condition
143
144 =cut
145
146 sub search_like {
147   my $class    = shift;
148   my $attrs = { };
149   if (@_ > 1 && ref $_[$#_] eq 'HASH') {
150     $attrs = pop(@_);
151   }
152   my $query    = ref $_[0] eq "HASH" ? { %{shift()} }: {@_};
153   $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
154   return $class->search($query, { %$attrs });
155 }
156
157 sub _select_columns {
158   return keys %{$_[0]->_columns};
159 }
160
161 =item table
162
163   __PACKAGE__->table('tbl_name');
164
165 =cut
166
167 sub table {
168   shift->_table_name(@_);
169 }
170
171 =item find_or_create
172
173   $class->find_or_create({ key => $val, ... });
174
175 Searches for a record matching the search condition; if it doesn't find one,
176 creates one and returns that instead
177
178 =cut
179
180 sub find_or_create {
181   my $class    = shift;
182   my $hash     = ref $_[0] eq "HASH" ? shift: {@_};
183   my $exists = $class->find($hash);
184   return defined($exists) ? $exists : $class->create($hash);
185 }
186
187 =item has_column                                                                
188                                                                                 
189   if ($obj->has_column($col)) { ... }                                           
190                                                                                 
191 Returns 1 if the object has a column of this name, 0 otherwise                  
192                                                                                 
193 =cut                                                                            
194
195 sub has_column {
196   my ($self, $column) = @_;
197   return exists $self->_columns->{$column};
198 }
199
200 =item column_info                                                               
201                                                                                 
202   my $info = $obj->column_info($col);                                           
203                                                                                 
204 Returns the column metadata hashref for the column                              
205                                                                                 
206 =cut                                                                            
207
208 sub column_info {
209   my ($self, $column) = @_;
210   die "No such column $column" unless exists $self->_columns->{$column};
211   return $self->_columns->{$column};
212 }
213
214 =item columns                                                                   
215                                                                                 
216   my @column_names = $obj->columns;                                             
217                                                                                 
218 =cut                                                                            
219
220 sub columns { return keys %{shift->_columns}; }
221
222 1;
223
224 =back
225
226 =head1 AUTHORS
227
228 Matt S. Trout <mst@shadowcatsystems.co.uk>
229
230 =head1 LICENSE
231
232 You may distribute this code under the same terms as Perl itself.
233
234 =cut
235