From: Jess Robinson <castaway@desert-island.me.uk>
Date: Sat, 14 Oct 2006 17:33:13 +0000 (+0000)
Subject: Minor consistency, layout and grammar updates
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=324572ca994f45d79f7dc80e9e8f90c10f35fe41;p=dbsrgits%2FDBIx-Class-Historic.git

Minor consistency, layout and grammar updates
---

diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod
index aae55bb..ada12c6 100644
--- a/lib/DBIx/Class/Manual/Cookbook.pod
+++ b/lib/DBIx/Class/Manual/Cookbook.pod
@@ -72,8 +72,10 @@ L<SQL::Abstract/WHERE CLAUSES>.
 
 =head3 Using specific columns
 
-When you only want selected columns from a table, you can use C<cols> to
-specify which ones you need:
+When you only want specific columns from a table, you can use
+C<columns> to specify which ones you need. This is useful to avoid
+loading columns with large amounts of data that you aren't about to
+use anyway:
 
   my $rs = $schema->resultset('Artist')->search(
     undef,
@@ -85,6 +87,9 @@ specify which ones you need:
   # Equivalent SQL:
   # SELECT artist.name FROM artist
 
+This is a shortcut for C<select> and C<as>, see below. C<columns>
+cannot be used together with C<select> and C<as>.
+
 =head3 Using database functions or stored procedures
 
 The combination of C<select> and C<as> can be used to return the result of a
@@ -94,7 +99,7 @@ stored procedure name). You then use C<as> to set the column name you will use
 to access the returned value:
 
   my $rs = $schema->resultset('Artist')->search(
-    undef,
+    {},
     {
       select => [ 'name', { LENGTH => 'name' } ],
       as     => [qw/ name name_length /],
@@ -105,15 +110,15 @@ to access the returned value:
   # SELECT name name, LENGTH( name ) name_length
   # FROM artist
 
-If your alias exists as a column in your base class (i.e. it was added with
-C<add_columns>), you just access it as normal. Our C<Artist> class has a C<name>
-column, so we just use the C<name> accessor:
+If your alias exists as a column in your base class (i.e. it was added
+with C<add_columns>), you just access it as normal. Our C<Artist>
+class has a C<name> column, so we just use the C<name> accessor:
 
   my $artist = $rs->first();
   my $name = $artist->name();
 
 If on the other hand the alias does not correspond to an existing column, you
-can get the value using the C<get_column> accessor:
+have to fetch the value using the C<get_column> accessor:
 
   my $name_length = $artist->get_column('name_length');
 
@@ -129,7 +134,7 @@ any of your aliases using either of these:
 =head3 SELECT DISTINCT with multiple columns
 
   my $rs = $schema->resultset('Foo')->search(
-    undef,
+    {},
     {
       select => [
         { distinct => [ $source->columns ] }
@@ -143,7 +148,7 @@ any of your aliases using either of these:
 =head3 SELECT COUNT(DISTINCT colname)
 
   my $rs = $schema->resultset('Foo')->search(
-    undef,
+    {},
     {
       select => [
         { count => { distinct => 'colname' } }
@@ -157,7 +162,7 @@ any of your aliases using either of these:
 L<DBIx::Class> supports C<GROUP BY> as follows:
 
   my $rs = $schema->resultset('Artist')->search(
-    undef,
+    {},
     {
       join     => [qw/ cds /],
       select   => [ 'name', { count => 'cds.cdid' } ],
@@ -173,7 +178,7 @@ L<DBIx::Class> supports C<GROUP BY> as follows:
 
 =head3 Predefined searches
 
-You can write your own DBIx::Class::ResultSet class by inheriting from it
+You can write your own L<DBIx::Class::ResultSet> class by inheriting from it
 and define often used searches as methods:
 
   package My::DBIC::ResultSet::CD;
@@ -539,7 +544,7 @@ For more complex stringification, you can use an anonymous subroutine:
   use overload '""' => sub { $_[0]->name . ", " .
                              $_[0]->address }, fallback => 1;
 
-=head3 Stringifcation Example
+=head3 Stringification Example
 
 Suppose we have two tables: C<Product> and C<Category>. The table
 specifications are:
@@ -723,33 +728,35 @@ The schema update can be deployed to customers using the same method as before.
 
 =head2 Setting limit dialect for SQL::Abstract::Limit
 
-In some cases, SQL::Abstract::Limit cannot determine the dialect of the remote
-SQL-server by looking at the database-handle. This is a common problem when
-using the DBD::JDBC, since the DBD-driver only know that in has a Java-driver
-available, not which JDBC-driver the Java component has loaded.
-This specifically sets the limit_dialect to Microsoft SQL-server (Se more names
-in SQL::Abstract::Limit -documentation.
+In some cases, SQL::Abstract::Limit cannot determine the dialect of
+the remote SQL server by looking at the database handle. This is a
+common problem when using the DBD::JDBC, since the DBD-driver only
+know that in has a Java-driver available, not which JDBC driver the
+Java component has loaded.  This specifically sets the limit_dialect
+to Microsoft SQL-server (See more names in SQL::Abstract::Limit
+-documentation.
 
   __PACKAGE__->storage->sql_maker->limit_dialect('mssql');
 
-The JDBC-bridge is one way of getting access to a MSSQL-server from a platform
+The JDBC bridge is one way of getting access to a MSSQL server from a platform
 that Microsoft doesn't deliver native client libraries for. (e.g. Linux)
 
-=head2 Setting quotes for the generated SQL. 
+=head2 Setting quoting for the generated SQL. 
 
-If the database contains columnames with spaces and/or reserved words, the
-SQL-query needs to be quoted. This is done using:
+If the database contains column names with spaces and/or reserved words, they
+need to be quoted in the SQL queries. This is done using:
 
   __PACKAGE__->storage->sql_maker->quote_char([ qw/[ ]/] );
   __PACKAGE__->storage->sql_maker->name_sep('.');
 
-The first sets the quotesymbols. If the quote i "symmetric" as " or '
+The first sets the quote characters. Either a pair of matching
+brackets, or a C<"> or C<'>:
   
   __PACKAGE__->storage->sql_maker->quote_char('"');
 
-is enough. If the left quote differs form the right quote, the first 
-notation should be used. name_sep needs to be set to allow the 
-SQL generator to put the quotes the correct place. 
+Check the documentation of your database for the correct quote
+characters to use. C<name_sep> needs to be set to allow the SQL
+generator to put the quotes the correct place.
 
 =head2 Overloading methods
 
@@ -774,11 +781,11 @@ You can accomplish this by overriding C<store_column>:
   }
 
 Note that the hard work is done by the call to C<next::method>, which
-redispatches your call to store_column to the superclass(es).
+redispatches your call to store_column in the superclass(es).
 
 =head3 Automatically creating related objects
 
-You might have a class C<Artist> which has many C<CD>s.  Further, you
+You might have a class C<Artist> which has many C<CD>s.  Further, if you
 want to create a C<CD> object every time you insert an C<Artist> object.
 You can accomplish this by overriding C<insert> on your objects:
 
@@ -838,11 +845,11 @@ L<Data::Dumper/EXAMPLES> for more information.
 
 =head2 Retrieving a row object's Schema
 
-It is possible to get a Schema object from a row object like so,
+It is possible to get a Schema object from a row object like so:
 
   my $schema = $cd->result_source->schema;
-  my $artist_rs = $schema->resultset('Artist');
-           # for example
+  # use the schema as normal:
+  my $artist_rs = $schema->resultset('Artist'); 
 
 This can be useful when you don't want to pass around a Schema object to every
 method.
@@ -923,19 +930,22 @@ not work, but then you already know the value of the last primary key anyway.
 =head2 Dynamic Sub-classing DBIx::Class proxy classes 
 (AKA multi-class object inflation from one table) 
  
-L<DBIx::Class> classes are proxy classes, therefore some different techniques 
-need to be employed for more than basic subclassing.  In this example we have  
-a single user table that carries a boolean bit for admin.  We would like  
-like to give the admin users objects(L<DBIx::Class::Row>) the same methods as  
-a regular user but also special admin only methods.  It doesn't make sense to  
-create two seperate proxy-class files for this.  We would be copying all the  
-user methods into the Admin class.  There is a cleaner way to accomplish this. 
-
-Overriding the C<inflate_results()> method within the User proxy-class gives 
-us the effect we want.  This method is called by L<DBIx::Class::ResultSet> when  
-inflating a result from storage.  So we grab the object being returned, inspect 
-the values we are looking for, bless it if it's an admin object, and then  
-return it.  Running the test file below will confirm this works. 
+L<DBIx::Class> classes are proxy classes, therefore some different
+techniques need to be employed for more than basic subclassing.  In
+this example we have a single user table that carries a boolean bit
+for admin.  We would like like to give the admin users
+objects(L<DBIx::Class::Row>) the same methods as a regular user but
+also special admin only methods.  It doesn't make sense to create two
+seperate proxy-class files for this.  We would be copying all the user
+methods into the Admin class.  There is a cleaner way to accomplish
+this.
+
+Overriding the C<inflate_results()> method within the User proxy-class
+gives us the effect we want.  This method is called by
+L<DBIx::Class::ResultSet> when inflating a result from storage.  So we
+grab the object being returned, inspect the values we are looking for,
+bless it if it's an admin object, and then return it.  See the example
+below:
  
 B<Schema Definition> 
  
@@ -957,7 +967,7 @@ B<Proxy-Class definitions>
     ### Defined what our admin class is for ensure_class_loaded 
     my $admin_class = __PACKAGE__ . '::Admin'; 
      
-    __PACKAGE__->load_components(qw/PK::Auto Core/); 
+    __PACKAGE__->load_components(qw/Core/); 
      
     __PACKAGE__->table('users');