From: Jess Robinson Date: Tue, 21 Mar 2006 18:47:26 +0000 (+0000) Subject: documenting! X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=30236e4788db222d813d881c71269e500b3f8385;p=dbsrgits%2FDBIx-Class-Historic.git documenting! --- diff --git a/lib/DBIx/Class/Relationship/Base.pm b/lib/DBIx/Class/Relationship/Base.pm index c838d69..4fb98bc 100644 --- a/lib/DBIx/Class/Relationship/Base.pm +++ b/lib/DBIx/Class/Relationship/Base.pm @@ -15,26 +15,39 @@ DBIx::Class::Relationship::Base - 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. +This class provides methods to describe the relationships between the +tables in your database model. These are the "bare bones" relationships +methods, for predefined ones, look in L. =head1 METHODS =head2 add_relationship +=head3 Arguments: ('relname', 'Foreign::Class', $cond, $attrs) + __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs); The condition needs to be an SQL::Abstract-style representation of the -join between the tables. For example, if you're creating a rel from Foo to Bar, +join between the tables. When resolving the condition for use in a JOIN, +keys using the psuedo-table I are resolved to mean "the Table on the +other side of the relationship", and values using the psuedo-table I +are resolved to mean "the Table this class is representing". Other +restrictions, such as by value, sub-select and other tables, may also be +used. Please check your database for JOIN parameter support. + +For example, if you're creating a rel from Author to Book, where the Book +table has a column author_id containing the ID of the Author row: - { 'foreign.foo_id' => 'self.id' } + { 'foreign.author_id' => 'self.id' } will result in the JOIN clause - foo me JOIN bar bar ON bar.foo_id = me.id + author me JOIN book book ON bar.author_id = me.id -You can specify as many foreign => self mappings as necessary. +You can specify as many foreign => self mappings as necessary. Each key/value +pair provided in a hashref will be used as ANDed conditions, to add an ORed +condition, use an arrayref of hashrefs. See the L documentation +for more details. Valid attributes are as follows: @@ -48,15 +61,18 @@ command immediately before C. =item proxy -An arrayref containing a list of accessors in the foreign class to proxy in +An arrayref containing a list of accessors in the foreign class to create in the main class. If, for example, you do the following: - __PACKAGE__->might_have(bar => 'Bar', undef, { proxy => [ qw/margle/ ] }); + MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes', undef, { + proxy => [ qw/notes/ ], + }); -Then, assuming Bar has an accessor named margle, you can do: +Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do: - my $obj = Foo->find(1); - $obj->margle(10); # set margle; Bar object is created if it doesn't exist + my $cd = MyDB::Schema::CD->find(1); + $cd->notes('Notes go here'); # set notes -- LinerNotes object is + # created if it doesn't exist =item accessor @@ -73,15 +89,59 @@ created, which calls C for the relationship. =head3 Arguments: ($relname, $rel_info) -Registers a relationship on the class +Registers a relationship on the class. This is called internally by +L to set up Accessors and Proxies. =cut sub register_relationship { } +=head2 related_resultset($name) + + $rs = $obj->related_resultset('related_table'); + +Returns a L for the relationship named $name. + +=cut + +sub related_resultset { + my $self = shift; + $self->throw_exception("Can't call *_related as class methods") unless ref $self; + my $rel = shift; + my $rel_obj = $self->relationship_info($rel); + $self->throw_exception( "No such relationship ${rel}" ) unless $rel_obj; + + return $self->{related_resultsets}{$rel} ||= do { + my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {}); + $attrs = { %{$rel_obj->{attrs} || {}}, %$attrs }; + + $self->throw_exception( "Invalid query: @_" ) if (@_ > 1 && (@_ % 2 == 1)); + my $query = ((@_ > 1) ? {@_} : shift); + + my $cond = $self->result_source->resolve_condition($rel_obj->{cond}, $rel, $self); + if (ref $cond eq 'ARRAY') { + $cond = [ map { my $hash; + foreach my $key (keys %$_) { + my $newkey = $key =~ /\./ ? "me.$key" : $key; + $hash->{$newkey} = $_->{$key}; + }; $hash } @$cond ]; + } else { + foreach my $key (grep { ! /\./ } keys %$cond) { + $cond->{"me.$key"} = delete $cond->{$key}; + } + } + $query = ($query ? { '-and' => [ $cond, $query ] } : $cond); + $self->result_source->related_source($rel)->resultset->search($query, $attrs); + }; +} + =head2 search_related - My::Table->search_related('relname', $cond, $attrs); + $rs->search_related('relname', $cond, $attrs); + +Run a search on a related resultset. The search will be restricted to the +item or items represented by the L it was called +upon. This method can be called on a ResultSet, a Row or a ResultSource class. =cut @@ -93,6 +153,9 @@ sub search_related { $obj->count_related('relname', $cond, $attrs); +Returns the count of all the items in the related resultset, restricted by +the current item or where conditions. Can be called on a L or a L object. + =cut sub count_related { @@ -100,9 +163,30 @@ sub count_related { return $self->search_related(@_)->count; } +=head2 new_related + + my $new_obj = $obj->new_related('relname', \%col_data); + +Create a new item of the related foreign class. If called on a +L object, it will magically +set any primary key values into foreign key columns for you. The newly +created item will not be saved into your storage until you call C +on it. + +=cut + +sub new_related { + my ($self, $rel, $values, $attrs) = @_; + return $self->search_related($rel)->new($values, $attrs); +} + =head2 create_related - My::Table->create_related('relname', \%col_data); + my $new_obj = $obj->create_related('relname', \%col_data); + +Creates a new item, similarly to new_related, and also inserts the item's data +into your storage medium. See the distinction between C and C +in L for details. =cut @@ -114,20 +198,12 @@ sub create_related { return $obj; } -=head2 new_related - - My::Table->new_related('relname', \%col_data); - -=cut - -sub new_related { - my ($self, $rel, $values, $attrs) = @_; - return $self->search_related($rel)->new($values, $attrs); -} - =head2 find_related - My::Table->find_related('relname', @pri_vals | \%pri_vals); + my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals); + +Attempt to find a related object using its primary key or unique constraints. +See C in L for details. =cut @@ -139,7 +215,10 @@ sub find_related { =head2 find_or_create_related - My::Table->find_or_create_related('relname', \%col_data); + my $new_obj = $obj->find_or_create_related('relname', \%col_data); + +Find or create an item of a related class. See C in +L for details. =cut @@ -150,7 +229,15 @@ sub find_or_create_related { =head2 set_from_related - My::Table->set_from_related('relname', $rel_obj); + $book->set_from_related('author', $author_obj); + +Set column values on the current object, using related values from the given +related object. This is used to associate previously separate objects, for +example, to set the correct author for a book, find the Author object, then +call set_from_related on the book. + +The columns are only set in the local copy of the object, call C to set +them in the storage. =cut @@ -173,7 +260,10 @@ sub set_from_related { =head2 update_from_related - My::Table->update_from_related('relname', $rel_obj); + $book->update_from_related('author', $author_obj); + +As C, but the changes are immediately updated onto your +storage. =cut @@ -185,7 +275,9 @@ sub update_from_related { =head2 delete_related - My::Table->delete_related('relname', $cond, $attrs); + $obj->delete_related('relname', $cond, $attrs); + +Delete any related item subject to the given conditions. =cut @@ -198,45 +290,6 @@ sub delete_related { 1; -=head2 related_resultset($name) - -Returns a L for the relationship named $name. - - $rs = $obj->related_resultset('related_table'); - -=cut - -sub related_resultset { - my $self = shift; - $self->throw_exception("Can't call *_related as class methods") unless ref $self; - my $rel = shift; - my $rel_obj = $self->relationship_info($rel); - $self->throw_exception( "No such relationship ${rel}" ) unless $rel_obj; - - return $self->{related_resultsets}{$rel} ||= do { - my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {}); - $attrs = { %{$rel_obj->{attrs} || {}}, %$attrs }; - - $self->throw_exception( "Invalid query: @_" ) if (@_ > 1 && (@_ % 2 == 1)); - my $query = ((@_ > 1) ? {@_} : shift); - - my $cond = $self->result_source->resolve_condition($rel_obj->{cond}, $rel, $self); - if (ref $cond eq 'ARRAY') { - $cond = [ map { my $hash; - foreach my $key (keys %$_) { - my $newkey = $key =~ /\./ ? "me.$key" : $key; - $hash->{$newkey} = $_->{$key}; - }; $hash } @$cond ]; - } else { - foreach my $key (grep { ! /\./ } keys %$cond) { - $cond->{"me.$key"} = delete $cond->{$key}; - } - } - $query = ($query ? { '-and' => [ $cond, $query ] } : $cond); - $self->result_source->related_source($rel)->resultset->search($query, $attrs); - }; -} - =head1 AUTHORS Matt S. Trout