Added an example

diff --git a/lib/DBIx/Class/Manual/Specification.pm b/lib/DBIx/Class/Manual/Specification.pm
index 539fc9f..b92ad36 100644 (file)
--- a/lib/DBIx/Class/Manual/Specification.pm
+++ b/lib/DBIx/Class/Manual/Specification.pm
@@ -203,6 +203,89 @@ needed. (q.v. Higher Order Perl for more information.)
 
 =head1 EXAMPLES
 
+  subtype Year as Num where { $_ > 0 && $_ <= 9999 };
+
+  table Artist {
+      column artist_id => ( isa => 'Num', auto_increment => 1, primary_key => 1 );
+      column name => ( isa => 'String', max_length => 50, nullable => 0 );
+      column rank => ( isa => 'Num', default => 13 );
+
+      has_many 'CD';
+
+      table 'artists';
+  }
+
+  table CD {
+      column cdid => ( isa => 'Num', auto_increment => 1, primary_key => 1 );
+      column artist => ( isa => 'Num' );
+      column title => ( isa => 'String', max_length => 100 );
+      column year => ( isa => 'Year' );
+
+      belongs_to 'Artist';
+
+      table 'cds';
+  }
+
+  # The following four searches are equivalent:
+  my @artists = $schema->table('Artist')->search({
+      name => 'Bon Jovi',
+  })->all;
+
+  my @artists = $schema->search({
+      name => 'Bon Jovi',
+  }, {
+      from => 'Artist',
+  });
+
+  # If a class and table name would conflict and they don't refer to the same
+  # thing, a compile-time error is thrown.
+  my @artists = $schema->search({
+      'Artist.name' => 'Bon Jovi',
+  });
+
+  my @artists = $schema->search({
+      'artists.name' => 'Bon Jovi',
+  });
+
+  # The following searches are equivalent. Results will contain objects that
+  # respond to artist_name(), cd_name(), and year() and nothing else.
+  my @results = $schema->search({
+      'Artist.name' => [ 'Bon Jovi', 'Metallica' ],
+      'CD.year'     => [ '2004', '2006' ],
+  }, {
+      select => [
+          [ 'Artist.name' => 'artist_name' ],
+          [ 'CD.name' => 'cd_name' ],
+          'CD.year',
+      ],
+  });
+
+  # Artist is the default table here.
+  my @results = $schema->table('Artist')->search({
+      'name'    => [ 'Bon Jovi', 'Metallica' ],
+      'CD.year' => [ '2004', '2006' ],
+  }, {
+      select => [
+          [ 'name' => 'artist_name' ],
+          [ 'CD.name' => 'cd_name' ],
+          'CD.year',
+      ],
+  });
+
+  # CD is the default table here.
+  my @results = $schema->table('CD')->search({
+      'Artist.name'    => [ 'Bon Jovi', 'Metallica' ],
+      'year' => [ '2004', '2006' ],
+  }, {
+      select => [
+          [ 'Artist.name' => 'artist_name' ],
+          [ 'name' => 'cd_name' ],
+          'year',
+      ],
+  });
+
+  # Note that joins are intuited through the existence of the relationships.
+
 =head1 TODO
 
 =over 4