Merge 'trunk' into 'DBIx-Class-current'

r7840@fortuna (orig r1262):  castaway | 2006-03-20 13:14:35 -0500
Add predefined searches patch from Hartmaier Alexander

r7841@fortuna (orig r1263):  matthewt | 2006-03-20 14:35:33 -0500
Marked deploy as experimental
r7844@fortuna (orig r1264):  castaway | 2006-03-20 16:03:58 -0500
de-foo documentation ;)

r7847@fortuna (orig r1265):  dwc | 2006-03-20 17:30:26 -0500
Fix exception text for nonexistent key in ResultSet::find()

diff --git a/Changes b/Changes
index 398f881..53d01f9 100644 (file)
--- a/Changes
+++ b/Changes
@@ -3,6 +3,7 @@ Revision history for DBIx::Class
 0.05999_05
         - Fixup to columns_info_for when database returns type(size)
         - Made do_txn respect void context (on the off-chance somebody cares)
+        - Fix exception text for nonexistent key in ResultSet::find()
 
 0.05999_04
         - Fix for delete on full-table resultsets

diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod
index 715c8f8..fc3224f 100644 (file)
--- a/lib/DBIx/Class/Manual/Cookbook.pod
+++ b/lib/DBIx/Class/Manual/Cookbook.pod
@@ -169,6 +169,37 @@ L<DBIx::Class> supports C<GROUP BY> as follows:
   # LEFT JOIN cd cds ON ( cds.artist = me.artistid )
   # GROUP BY name
 
+=head3 Predefined searches
+
+You can write your own DBIx::Class::ResultSet class by inheriting from it
+and define often used searches as methods:
+
+  package My::DBIC::ResultSet::CD;
+  use strict;
+  use warnings;
+  use base 'DBIx::Class::ResultSet';
+
+  sub search_cds_ordered {
+      my ($self) = @_;
+
+      return $self->search(
+          {},
+          { order_by => 'name DESC' },
+      );
+  }
+
+  1;
+
+To use your resultset, first tell DBIx::Class to create an instance of it
+for you, in your My::DBIC::Schema::CD class:
+
+  __PACKAGE__->resultset_class('My::DBIC::ResultSet::CD');
+
+Then call your new method in your code:
+
+   my $ordered_cds = $schema->resultset('CD')->search_cds_ordered();
+
+
 =head2 Using joins and prefetch
 
 You can use the C<join> attribute to allow searching on, or sorting your

diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm
index 22be1d3..68a223e 100644 (file)
--- a/lib/DBIx/Class/Relationship.pm
+++ b/lib/DBIx/Class/Relationship.pm
@@ -40,10 +40,10 @@ See L<DBIx::Class::Relationship::Base> for a list of valid attributes.
 
 =head2 belongs_to
 
-  # in a Bar class (where Foo has many Bars)
-  __PACKAGE__->belongs_to(foo => Foo);
-  my $f_obj = $obj->foo;
-  $obj->foo($new_f_obj);
+  # in a Book class (where Author has many Books)
+  My::DBIC::Schema::Book->belongs_to(author => 'Author');
+  my $author_obj = $obj->author;
+  $obj->author($new_author_obj);
 
 Creates a relationship where the calling class stores the foreign class's 
 primary key in one (or more) of its columns. If $cond is a column name
@@ -56,13 +56,13 @@ of C<has_a>.
 
 =head2 has_many
 
-  # in a Foo class (where Foo has many Bars)
-  __PACKAGE__->has_many(bar => Bar, 'foo');
-  my $f_resultset = $obj->foo;
-  my $f_resultset = $obj->foo({ name => { LIKE => '%macaroni%' }, { prefetch => [qw/bar/] });
-  my @f_obj = $obj->foo;
+  # in an Author class (where Author has many Books)
+  My::DBIC::Schema::Author->has_many(books => 'Book', 'author');
+  my $booklist = $obj->books;
+  my $booklist = $obj->books({ name => { LIKE => '%macaroni%' }, { prefetch => [qw/book/] });
+  my @book_objs = $obj->books;
 
-  $obj->add_to_foo(\%col_data);
+  $obj->add_to_books(\%col_data);
 
 Creates a one-to-many relationship, where the corresponding elements of the
 foreign class store the calling class's primary key in one (or more) of its
@@ -75,32 +75,33 @@ cascade or restrict will take precedence.
 
 =head2 might_have
 
-  __PACKAGE__->might_have(baz => Baz);
-  my $f_obj = $obj->baz; # to get the baz object
+  My::DBIC::Schema::Author->might_have(psuedonym => 'Psuedonyms');
+  my $pname = $obj->psuedonym; # to get the Psuedonym object
 
-Creates an optional one-to-one relationship with a class, where the foreign class 
-stores our primary key in one of its columns. Defaults to the primary key of the
-foreign class unless $cond specifies a column or join condition.
+Creates an optional one-to-one relationship with a class, where the foreign
+class stores our primary key in one of its columns. Defaults to the primary
+key of the foreign class unless $cond specifies a column or join condition.
 
-If you update or delete an object in a class with a C<might_have> relationship, 
-the related object will be updated or deleted as well. Any database-level update
-or delete constraints will override this behavior.
+If you update or delete an object in a class with a C<might_have>
+relationship, the related object will be updated or deleted as well.
+Any database-level update or delete constraints will override this behaviour.
 
 =head2 has_one
 
-  __PACKAGE__->has_one(gorch => Gorch);
-  my $f_obj = $obj->gorch;
+  My::DBIC::Schema::Book->has_one(isbn => ISBN);
+  my $isbn_obj = $obj->isbn;
 
-Creates a one-to-one relationship with another class. This is just like C<might_have>,
-except the implication is that the other object is always present. The only different
-between C<has_one> and C<might_have> is that C<has_one> uses an (ordinary) inner join,
-whereas C<might_have> uses a left join.
+Creates a one-to-one relationship with another class. This is just like
+C<might_have>, except the implication is that the other object is always
+present. The only difference between C<has_one> and C<might_have> is that
+C<has_one> uses an (ordinary) inner join, whereas C<might_have> uses a
+left join.
 
 
 =head2 many_to_many
 
-  __PACKAGE__->many_to_many( 'accessorname' => 'a_to_b', 'table_b' );
-  my @f_objs = $obj_a->accessorname;
+  My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles', 'Roles' );
+  my @role_objs = $obj_a->roles;
 
 Creates an accessor bridging two relationships; not strictly a relationship
 in its own right, although the accessor will return a resultset or collection

diff --git a/lib/DBIx/Class/ResultSet.pm b/lib/DBIx/Class/ResultSet.pm
index da955a4..da9dced 100644 (file)
--- a/lib/DBIx/Class/ResultSet.pm
+++ b/lib/DBIx/Class/ResultSet.pm
@@ -252,7 +252,7 @@ sub find {
   my @cols = $self->result_source->primary_columns;
   if (exists $attrs->{key}) {
     my %uniq = $self->result_source->unique_constraints;
-    $self->throw_exception( "Unknown key $attrs->{key} on $self->name" )
+    $self->throw_exception( "Unknown key $attrs->{key} on '" . $self->result_source->name . "'" )
       unless exists $uniq{$attrs->{key}};
     @cols = @{ $uniq{$attrs->{key}} };
   }

diff --git a/lib/DBIx/Class/Schema.pm b/lib/DBIx/Class/Schema.pm
index 7df9d5f..114c04b 100644 (file)
--- a/lib/DBIx/Class/Schema.pm
+++ b/lib/DBIx/Class/Schema.pm
@@ -547,9 +547,12 @@ sub throw_exception {
   croak @_;
 }
 
-=head2 deploy
+=head2 deploy (EXPERIMENTAL)
 
-Attempts to deploy the schema to the current storage
+Attempts to deploy the schema to the current storage using SQL::Translator.
+
+Note that this feature is currently EXPERIMENTAL and may not work correctly
+across all databases, or fully handle complex relationships.
 
 =cut