Documentation update and cleanup

This update removes 'year' from the CD table definition in both the SQL
and in the class definition, since it wasn't being used. The directory
MyApp/Schema/ResultSet was also removed since the supplied code never
used it.

The results that the sample code produces have been expanded a little so
that they provide answers to the questions asked by the subroutine
calls.

A new section has been added that briefly discusses the results and
explains the techniques that could be used when writing this type of a
programmatic query.

diff --git a/lib/DBIx/Class/Manual/Example.pod b/lib/DBIx/Class/Manual/Example.pod
index 59b114e..05db57b 100644 (file)
--- a/lib/DBIx/Class/Manual/Example.pod
+++ b/lib/DBIx/Class/Manual/Example.pod
@@ -11,7 +11,7 @@ as the database frontend.
 The database consists of the following:
 
   table 'artist' with columns:  artistid, name
-  table 'cd'     with columns:  cdid, artist, title, year
+  table 'cd'     with columns:  cdid, artist, title
   table 'track'  with columns:  trackid, cd, title
 
 
@@ -25,21 +25,22 @@ And these rules exists:
 
 =head2 Installation
 
-Install DBIx::Class via CPAN should be sufficient.
+You'll need to install DBIx::Class via CPAN, and you'll also need to
+install sqlite3 (not sqlite) if it's not already intalled.
 
 =head3 Create the database/tables
 
-First make and change the directory:
+First, create the database directory, then get into that directory, as
+we'll create the database there:
 
   mkdir app
-  cd app
-  mkdir db
-  cd db
+  mkdir app/db
+  cd app/db
 
 This example uses SQLite which is a dependency of DBIx::Class, so you
 shouldn't have to install extra software.
 
-Save the following into a example.sql in the directory db
+Save the following into a example.sql in the directory app/db
 
   CREATE TABLE artist (
     artistid INTEGER PRIMARY KEY,
@@ -68,14 +69,13 @@ Change directory back from db to the directory app:
 
   cd ../
 
-Now create some more directories:
+Now we'll create some more directories for the classes:
 
   mkdir MyApp
   mkdir MyApp/Schema
   mkdir MyApp/Schema/Result
-  mkdir MyApp/Schema/ResultSet
 
-Then, create the following DBIx::Class::Schema classes:
+Create the following DBIx::Class::Schema classes:
 
 MyApp/Schema.pm:
 
@@ -104,7 +104,7 @@ MyApp/Schema/Result/Cd.pm:
   use base qw/DBIx::Class::Core/;
   __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
   __PACKAGE__->table('cd');
-  __PACKAGE__->add_columns(qw/ cdid artist title year/);
+  __PACKAGE__->add_columns(qw/ cdid artist title /);
   __PACKAGE__->set_primary_key('cdid');
   __PACKAGE__->belongs_to('artist' => 'MyApp::Schema::Result::Artist');
   __PACKAGE__->has_many('tracks' => 'MyApp::Schema::Result::Track');
@@ -126,7 +126,10 @@ MyApp/Schema/Result/Track.pm:
 
 =head3 Write a script to insert some records
 
-insertdb.pl
+This script should be created in the app/ directory, since it access the
+database in the app/db directory.
+
+insertdb.pl:
 
   #!/usr/bin/perl
 
@@ -186,8 +189,14 @@ insertdb.pl
     @tracks,
   ]);
 
+Once created, this script should be run once to fill the database with
+the required data for the following test script.
+
 =head3 Create and run the test scripts
 
+Like the previous script, this script should also be create in the app/
+directory.
+
 testdb.pl:
 
   #!/usr/bin/perl
@@ -242,7 +251,8 @@ testdb.pl:
       }
     );
     while (my $track = $rs->next) {
-      print $track->title . "\n";
+      print $track->title . " (from the CD '" . $track->cd->title 
+        . "')\n";
     }
     print "\n";
   }
@@ -260,7 +270,7 @@ testdb.pl:
       }
     );
     my $cd = $rs->first;
-    print $cd->title . "\n\n";
+    print $cd->title . " has the track '$tracktitle'.\n\n";
   }
 
   sub get_cds_by_artist {
@@ -296,7 +306,7 @@ testdb.pl:
       }
     );
     my $artist = $rs->first;
-    print $artist->name . "\n\n";
+    print $artist->name . " recorded the track '$tracktitle'.\n\n";
   }
 
   sub get_artist_by_cd {
@@ -311,37 +321,51 @@ testdb.pl:
       }
     );
     my $artist = $rs->first;
-    print $artist->name . "\n\n";
+    print $artist->name . " recorded the CD '$cdtitle'.\n\n";
   }
 
 
 
-It should output:
-
-  get_tracks_by_cd(Bad):
-  Dirty Diana
-  Smooth Criminal
-  Leave Me Alone
-
-  get_tracks_by_artist(Michael Jackson):
-  Beat it
-  Billie Jean
-  Dirty Diana
-  Smooth Criminal
-  Leave Me Alone
-
-  get_cd_by_track(Stan):
-  The Marshall Mathers LP
-
-  get_cds_by_artist(Michael Jackson):
-  Thriller
-  Bad
-
-  get_artist_by_track(Dirty Diana):
-  Michael Jackson
-
-  get_artist_by_cd(The Marshall Mathers LP):
-  Eminem
+When this script is run, it should output the following:
+
+ get_tracks_by_cd(Bad):
+ Leave Me Alone
+ Smooth Criminal
+ Dirty Diana
+ 
+ get_tracks_by_artist(Michael Jackson):
+ Billie Jean (from the CD 'Thriller')
+ Leave Me Alone (from the CD 'Bad')
+ Smooth Criminal (from the CD 'Bad')
+ Beat It (from the CD 'Thriller')
+ Dirty Diana (from the CD 'Bad')
+ 
+ get_cd_by_track(Stan):
+ The Marshall Mathers LP has the track 'Stan'.
+ 
+ get_cds_by_artist(Michael Jackson):
+ Thriller
+ Bad
+ 
+ get_artist_by_track(Dirty Diana):
+ Michael Jackson recorded the track 'Dirty Diana'.
+ 
+ get_artist_by_cd(The Marshall Mathers LP):
+ Eminem recorded the CD 'The Marshall Mathers LP'.
+
+=head3 Discussion about the results
+
+The data model defined in this example has an artist with multiple CDs,
+and a CD with multiple tracks; thus, it's simple to traverse from a
+track back to a CD, and from there back to an artist. This is
+demonstrated in the get_tracks_by_artist routine, where we easily walk
+from the individual track back to the title of the CD that the track
+came from ($track->cd->title).
+
+Note also that in the get_tracks_by_cd and get_tracks_by_artist
+routines, the result set is called multiple times with the 'next'
+iterator.  In contrast, get_cd_by_track uses the 'first' result set
+method, since only one CD is expected to have a specific track.
 
 =head1 Notes