Merge 'find_changes' into 'DBIx-Class-current'

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Relationship / Base.pm

diff --git a/lib/DBIx/Class/Relationship/Base.pm b/lib/DBIx/Class/Relationship/Base.pm
index c3733e7..c30c8e2 100644 (file)
--- a/lib/DBIx/Class/Relationship/Base.pm
+++ b/lib/DBIx/Class/Relationship/Base.pm
@@ -5,7 +5,7 @@ use warnings;
 
 use base qw/DBIx::Class/;
 
-=head1 NAME 
+=head1 NAME
 
 DBIx::Class::Relationship::Base - Inter-table relationships
 
@@ -15,7 +15,7 @@ DBIx::Class::Relationship::Base - Inter-table relationships
 
 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<DBIx::Class::Relationship>. 
+methods, for predefined ones, look in L<DBIx::Class::Relationship>.
 
 =head1 METHODS
 
@@ -23,7 +23,7 @@ methods, for predefined ones, look in L<DBIx::Class::Relationship>.
 
 =over 4
 
-=item Arguments: ('relname', 'Foreign::Class', $cond, $attrs)
+=item Arguments: 'relname', 'Foreign::Class', $cond, $attrs
 
 =back
 
@@ -92,7 +92,7 @@ created, which calls C<create_related> for the relationship.
 
 =over 4
 
-=item Arguments: ($relname, $rel_info)
+=item Arguments: $relname, $rel_info
 
 =back
 
@@ -107,9 +107,9 @@ sub register_relationship { }
 
 =over 4
 
-=item Arguments: ($relationship_name)
+=item Arguments: $relationship_name
 
-=item Returns: $related_resultset
+=item Return Value: $related_resultset
 
 =back
 
@@ -238,12 +238,27 @@ sub find_related {
   return $self->search_related($rel)->find(@_);
 }
 
+=head2 find_or_new_related
+
+  my $new_obj = $obj->find_or_new_related('relname', \%col_data);
+
+Find an item of a related class. If none exists, instantiate a new item of the
+related class. The object will not be saved into your storage until you call
+L<DBIx::Class::Row/insert> on it.
+
+=cut
+
+sub find_or_new_related {
+  my $self = shift;
+  return $self->find_related(@_) || $self->new_related(@_);
+}
+
 =head2 find_or_create_related
 
   my $new_obj = $obj->find_or_create_related('relname', \%col_data);
 
 Find or create an item of a related class. See
-L<DBIx::Class::ResultSet/"find_or_create"> for details.
+L<DBIx::Class::ResultSet/find_or_create> for details.
 
 =cut
 
@@ -252,6 +267,21 @@ sub find_or_create_related {
   return $self->find_related(@_) || $self->create_related(@_);
 }
 
+=head2 update_or_create_related
+
+  my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
+
+Update or create an item of a related class. See
+L<DBIx::Class::ResultSet/"update_or_create"> for details.
+
+=cut
+
+sub update_or_create_related {
+  my $self = shift;
+  my $rel = shift;
+  return $self->related_resultset($rel)->update_or_create(@_);
+}
+
 =head2 set_from_related
 
   $book->set_from_related('author', $author_obj);