From: Marcus Ramberg Date: Fri, 14 Oct 2005 15:21:07 +0000 (+0000) Subject: More docs. X-Git-Tag: v0.05005~199 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=ee38fa40d848a164040097286b4440d4b64565e8;p=dbsrgits%2FDBIx-Class.git More docs. --- diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod new file mode 100644 index 0000000..8fd5e0a --- /dev/null +++ b/lib/DBIx/Class/Manual/Cookbook.pod @@ -0,0 +1,68 @@ +=head1 DBIx::Class Cookbook + +=over 4 + +=item Input validation. + +=item Using joins + +=item Many-to-many relationships + +This is not as easy as it could be, but it's possible. Here's an example to +illustrate: + + package Base; + + use base qw/DBIx::Class/; + + __PACKAGE__->load_components(qw/Core DB/); + __PACKAGE__->connection(...); + + package Left; + + use base qw/Base/; + + __PACKAGE__->table('left'); + __PACKAGE__->add_columns(qw/id left_stuff/); + __PACKAGE__->set_primary_key(qw/id/); + __PACKAGE__->has_many('mid' => 'Mid'); + + sub right { + my ($self) = @_; + return Right->search( + { 'left.id' => $self->id }, + { join => { 'mid' => 'left' }}); + } + + package Mid; + + use base qw/Base/; + + __PACKAGE__->table('mid'); + __PACKAGE__->add_columns(qw/left right/); + __PACKAGE__->set_primary_key(qw/left right/); + + __PACKAGE__->belongs_to('left' => 'Left'); + __PACKAGE__->belongs_to('right' => 'Right'); + + package Right; + + use base qw/Base/; + + __PACKAGE__->table('right'); + __PACKAGE__->add_columns(qw/id right_stuff/); + __PACKAGE__->set_primary_key(qw/id/); + __PACKAGE__->has_many('mid' => 'Mid'); + + sub left { + my ($self) = @_; + return Left->search( + { 'right.id' => $self->id }, + { join => { 'mid' => 'right' }); + } + +=item Advanced Exception handling + +=item Transactions + +=back diff --git a/lib/DBIx/Class/Manual/FAQ.pod b/lib/DBIx/Class/Manual/FAQ.pod new file mode 100644 index 0000000..7400bb9 --- /dev/null +++ b/lib/DBIx/Class/Manual/FAQ.pod @@ -0,0 +1,20 @@ +=head1 Frequetly Asked Questions + +=over 4 + +=item What is the point of this module? Is it a fork of Class::DBI? + +=item Who's the intended audience for this module? + +=item What databases does it support? + +=item What's the current status of this module? + +=item What's planned in the future? + +=item Where can I go for support? + +=back + +=cut + diff --git a/lib/DBIx/Class/Manual/Troubleshooting.pod b/lib/DBIx/Class/Manual/Troubleshooting.pod new file mode 100644 index 0000000..ebfb71b --- /dev/null +++ b/lib/DBIx/Class/Manual/Troubleshooting.pod @@ -0,0 +1,10 @@ +=head1 Troubleshooting + +=over 4 + +=item + +=back + +=cut + diff --git a/lib/DBIx/Class/ResultSet.pm b/lib/DBIx/Class/ResultSet.pm index c56480a..6178af7 100644 --- a/lib/DBIx/Class/ResultSet.pm +++ b/lib/DBIx/Class/ResultSet.pm @@ -7,6 +7,29 @@ use overload fallback => 1; use Data::Page; +=head1 NAME + +DBIX::Class::Recordset - Responsible for fetching and creating recordsets. + +=head1 SYNOPSIS; + +$rs=MyApp::DB::Class->search(registered=>1); + +=head1 DESCRIPTION + +The recordset is also know as an iterator. + +=head1 METHODS + +=over 4 + +=item new + +The recordset constructor. Takes a db class and an +attribute hash (see below for more info on attributes) + +=cut + sub new { my ($it_class, $db_class, $attrs) = @_; #use Data::Dumper; warn Dumper(@_); @@ -46,6 +69,12 @@ sub new { return $new; } +=item cursor + +Return a storage driven cursor to the given record set. + +=cut + sub cursor { my ($self) = @_; my ($db_class, $attrs) = @{$self}{qw/class attrs/}; @@ -58,6 +87,12 @@ sub cursor { $attrs->{where},$attrs); } +=item slice + +return a number of elements from the given record set. + +=cut + sub slice { my ($self, $min, $max) = @_; my $attrs = { %{ $self->{attrs} || {} } }; @@ -68,6 +103,12 @@ sub slice { return (wantarray ? $slice->all : $slice); } +=item next + +Returns the next element in this record set. + +=cut + sub next { my ($self) = @_; my @row = $self->cursor->next; @@ -109,6 +150,14 @@ sub _construct_object { return $new; } +=item count + +Performs an SQL count with the same query as the resultset was built +with to find the number of elements. + +=cut + + sub count { my ($self) = @_; my $db_class = $self->{class}; @@ -128,22 +177,47 @@ sub count { : $self->{count}; } +=item all + +Returns all elements in the recordset. Is called implictly if the search +method is used in list context. + +=cut + sub all { my ($self) = @_; return map { $self->_construct_object(@$_); } $self->cursor->all; } +=item reset + +Reset this recordset's cursor, so you can iterate through the elements again. + +=cut + sub reset { my ($self) = @_; $self->cursor->reset; return $self; } +=item first + +resets the recordset and returns the first element. + +=cut + sub first { return $_[0]->reset->next; } +=item delete + +Deletes all elements in the recordset. + +=cut + sub delete { my ($self) = @_; $_->delete for $self->all; @@ -152,6 +226,13 @@ sub delete { *delete_all = \&delete; # Yeah, yeah, yeah ... +=item pager + +Returns a L object for the current resultset. Only makes +sense for queries with page turned on. + +=cut + sub pager { my ($self) = @_; my $attrs = $self->{attrs}; @@ -163,6 +244,12 @@ sub pager { return $self->{pager}; } +=item page + +Returns a new recordset representing a given page. + +=cut + sub page { my ($self, $page) = @_; my $attrs = $self->{attrs}; @@ -170,14 +257,7 @@ sub page { return $self->new($self->{class}, $attrs); } -=head1 NAME - -DBIX::Class::Recordset - Responsible for fetching and creating recordsets. - -=head1 SYNOPSIS; - -$rs=MyApp::DB::Class->search(registered=>1); - +=back =head1 Attributes @@ -189,6 +269,24 @@ can be passed in with the search functions. Here's an overview of them: =item order_by Which column to order the results by. + +=item cols + +Which cols should be retrieved on the first search. + +=item join + +Contains a list of relations that should be joined for this query. Can also +contain a hash referece to refer to that relation's relations. + +=item from + +This attribute can contain a arrayref of elements. each element can be another +arrayref, to nest joins, or it can be a hash which represents the two sides +of the join. + +*NOTE* Use this on your own risk. This allows you to shoot your foot off! + =item page Should the resultset be paged? This can also be enabled by using the @@ -202,6 +300,11 @@ For paged resultsset, how many rows per page For paged resultsset, which page to start on. +=item accesor + +Tells the recordset how to prefetch relations. Can either be 'single' or +'filter'. + =back 1;