From: David Kamholz Date: Sat, 10 Dec 2005 15:48:13 +0000 (+0000) Subject: docs updates to Relationship and ResultSet X-Git-Tag: v0.05005~149 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=df8abd99a70d8d8af5046da841557e1a394b752b;p=dbsrgits%2FDBIx-Class.git docs updates to Relationship and ResultSet --- diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm index fd9152f..65d646e 100644 --- a/lib/DBIx/Class/Relationship.pm +++ b/lib/DBIx/Class/Relationship.pm @@ -26,37 +26,56 @@ DBIx::Class::Relationship - Inter-table relationships =head1 DESCRIPTION This class handles relationships between the tables in your database -model. It allows your to set up relationships, and to perform joins -on searches. +model. It allows you to set up relationships and perform joins on them. -This POD details only the convenience methods for setting up standard -relationship types. For more information see ::Relationship::Base +Only the helper methods for setting up standard relationship types +are documented here. For the basic, lower-level methods, see +L. =head1 METHODS -All convenience methods take a signature of the following format - +All helper methods take the following arguments: - __PACKAGE__>method_name('relname', 'Foreign::Class', $join?, $attrs?); + __PACKAGE__>method_name('relname', 'Foreign::Class', $cond, $attrs); + +Both C<$cond> and C<$attrs> are optional. Pass C for C<$cond> if +you want to use the default value for it, but still want to set C<$attrs>. +The following attributes are recognize: +=over 4 +=item join_type -=over 4 +Explicitly specifies the type of join to use in the relationship. Any SQL +join type is valid, e.g. C or C. It will be placed in the SQL +command immediately before C. -=item has_one +=item proxy - my $f_obj = $obj->relname; +An arrayref containing a list of accessors in the foreign class to proxy in +the main class. If, for example, you do the following: + + __PACKAGE__->might_have(bar => 'Bar', undef, { proxy => qw[/ margle /] }); + +Then, assuming Bar has an accessor named margle, you can do: -Creates a one-one relationship with another class; defaults to PK-PK for -the join condition unless a condition is specified. + my $obj = Foo->find(1); + $obj->margle(10); # set margle; Bar object is created if it doesn't exist + +=back -=item might_have +=head2 belongs_to my $f_obj = $obj->relname; -Creates an optional one-one relationship with another class; defaults to PK-PK -for the join condition unless a condition is specified. + $obj->relname($new_f_obj); + +Creates a relationship where we store the foreign class' PK; if $join is a +column name instead of a condition that is assumed to be the FK, if not +has_many assumes the FK is the relname is that is a column on the current +class. -=item has_many +=head2 has_many my @f_obj = $obj->relname($cond?, $attrs?); my $f_result_set = $obj->relname($cond?, $attrs?); @@ -65,23 +84,24 @@ for the join condition unless a condition is specified. Creates a one-many relationship with another class; -=item belongs_to +=head2 might_have my $f_obj = $obj->relname; - $obj->relname($new_f_obj); +Creates an optional one-one relationship with another class; defaults to PK-PK +for the join condition unless a condition is specified. -Creates a relationship where we store the foreign class' PK; if $join is a -column name instead of a condition that is assumed to be the FK, if not -has_many assumes the FK is the relname is that is a column on the current -class. +=head2 has_one + + my $f_obj = $obj->relname; + +Creates a one-one relationship with another class; defaults to PK-PK for +the join condition unless a condition is specified. =cut 1; -=back - =head1 AUTHORS Matt S. Trout diff --git a/lib/DBIx/Class/ResultSet.pm b/lib/DBIx/Class/ResultSet.pm index 5595272..eae9193 100644 --- a/lib/DBIx/Class/ResultSet.pm +++ b/lib/DBIx/Class/ResultSet.pm @@ -11,22 +11,24 @@ use Data::Page; DBIx::Class::ResultSet - Responsible for fetching and creating resultset. -=head1 SYNOPSIS; +=head1 SYNOPSIS -$rs=MyApp::DB::Class->search(registered=>1); +my $rs = MyApp::DB::Class->search(registered => 1); +my @rows = MyApp::DB::Class->search(foo => 'bar'); =head1 DESCRIPTION -The resultset is also known as an iterator. +The resultset is also known as an iterator. It is responsible for handling +queries that may return an arbitrary number of rows, e.g. via C +or a C relationship. =head1 METHODS -=over 4 +=head2 new($db_class, \%$attrs) -=item new - -The resultset constructor. Takes a db class and an -attribute hash (see below for more info on attributes) +The resultset constructor. Takes a table class and an attribute hash +(see below for more information on attributes). Does not perform +any queries -- these are executed as needed by the other methods. =cut @@ -69,9 +71,9 @@ sub new { return $new; } -=item cursor +=head2 cursor -Return a storage driven cursor to the given resultset. +Return a storage-driven cursor to the given resultset. =cut @@ -87,9 +89,9 @@ sub cursor { $attrs->{where},$attrs); } -=item slice +=head2 slice($first, $last) -return a number of elements from the given resultset. +Returns a subset of elements from the resultset. =cut @@ -103,9 +105,9 @@ sub slice { return (wantarray ? $slice->all : $slice); } -=item next +=head2 next -Returns the next element in this resultset. +Returns the next element in the resultset (undef is there is none). =cut @@ -155,14 +157,13 @@ sub _construct_object { return $new; } -=item count +=head2 count -Performs an SQL count with the same query as the resultset was built +Performs an SQL C 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}; @@ -182,10 +183,10 @@ sub count { : $self->{count}; } -=item all +=head2 all -Returns all elements in the resultset. Is called implictly if the search -method is used in list context. +Returns all elements in the resultset. Called implictly if the resultset +is returned in list context. =cut @@ -195,9 +196,9 @@ sub all { $self->cursor->all; } -=item reset +=head2 reset -Reset this resultset's cursor, so you can iterate through the elements again. +Resets the resultset's cursor, so you can iterate through the elements again. =cut @@ -207,9 +208,9 @@ sub reset { return $self; } -=item first +=head2 first -resets the resultset and returns the first element. +Resets the resultset and returns the first element. =cut @@ -217,7 +218,7 @@ sub first { return $_[0]->reset->next; } -=item delete +=head2 delete Deletes all elements in the resultset. @@ -231,7 +232,7 @@ sub delete { *delete_all = \&delete; # Yeah, yeah, yeah ... -=item pager +=head2 pager Returns a L object for the current resultset. Only makes sense for queries with page turned on. @@ -249,9 +250,9 @@ sub pager { return $self->{pager}; } -=item page +=head2 page($page_num) -Returns a new resultset representing a given page. +Returns a new resultset for the specified page. =cut @@ -262,49 +263,48 @@ sub page { return $self->new($self->{class}, $attrs); } -=back - =head1 Attributes -The resultset is responsible for handling the various attributes that -can be passed in with the search functions. Here's an overview of them: - -=over 4 +The resultset takes various attributes that modify its behavior. +Here's an overview of them: -=item order_by +=head2 order_by -Which column to order the results by. +Which column(s) to order the results by. This is currently passed +through directly to SQL, so you can give e.g. C for a +descending order. -=item cols +=head2 cols -Which cols should be retrieved on the first search. +Which columns should be retrieved. -=item join +=head2 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. +contain a hash reference to refer to that relation's relations. So, if one column +in your class C foo and another C bar, you can do +C<< join => [qw/ foo bar /] >> to join both (and e.g. use them for C). +If a foo contains many margles and you want to join those too, you can do +C<< join => { foo => 'margle' } >>. If you want to fetch the columns from the +related table as well, see C below. -=item from +=head2 from -This attribute can contain a arrayref of elements. each element can be another +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! +NOTE: Use this on your own risk. This allows you to shoot your foot off! -=item page +=head2 page -Should the resultset be paged? This can also be enabled by using the -'page' option. +For a paged resultset, specifies which page to retrieve. Leave unset +for an unpaged resultset. -=item rows +=head2 rows -For paged resultsset, how many rows per page +For a paged resultset, how many rows per page -=item offset - -For paged resultsset, which page to start on. - -=back +=cut 1;