From: Alex Beamish Date: Wed, 4 Sep 2013 17:45:39 +0000 (-0400) Subject: Documentation update and cleanup X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=refs%2Fheads%2Fghpr%2Frejected%2Finspiring_67c07caa;p=dbsrgits%2FDBIx-Class-Historic.git 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 --- 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