X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FManual%2FSpecification.pm;fp=lib%2FDBIx%2FClass%2FManual%2FSpecification.pm;h=539fc9f61e655d634dc049a3607f4f716e5340fb;hb=8b8bab95213fd36c8e0d447b13f38cbad9e9a6b6;hp=4fc09f91c3c7718ad70b859c9ccbeec42647bf6b;hpb=7848cf7a67ef93ea2ac29e65c23a7fa0b177dad1;p=dbsrgits%2Fdbic-future.git

diff --git a/lib/DBIx/Class/Manual/Specification.pm b/lib/DBIx/Class/Manual/Specification.pm
index 4fc09f9..539fc9f 100644
--- a/lib/DBIx/Class/Manual/Specification.pm
+++ b/lib/DBIx/Class/Manual/Specification.pm
@@ -133,17 +133,21 @@ allow for creation and, possibly, deletion. Most ORMs do this modelling by
 mapping a class to a table and an instance of that class to a given row in that
 table. 
 
-DBIx::Class takes a different approach. Given rows in a table are represented by
-objects, but the table as a whole is also represented by an object. There is no
-class that represents the table in itself. Instead, there is a class that is
-used to instantiate the rows of a table and another class that is used to
-instantiate objects that represent SQL clauses for statements against that
-table. The former is the Row class and the latter is the ResultSet class.  This
-separation allows for greater expressivity when dealing with a given table.
+DBIx::Class takes a different approach entirely. Instead of treating the row as
+the atomic unit, DBIx::Class 09 will treat the column as the atomic unit. This
+opens up several possibilities:
 
-DBIx::Class 0.09 extends these concepts by adding a third layer - the source.
+=over 4
 
-(Expand here.)
+=item * The definition of a table fall out naturally as a collection of columns
+
+=item * Defining custom searches is a matter of creating a collection of columns on the fly.
+
+=item * Validating values is easily handled regardless of where the column is used.
+
+=item * Enumeration tables can be hidden behind a column definition, allowing optimization to ENUM as appropriate.
+
+=back
 
 =head3 Sources
 
@@ -155,7 +159,10 @@ extreme, the FROM clause of a query forms a single source. A subquery can also
 be viewed as a source. (In fact, any table or join can be viewed as the subquery
 "(SELECT * FROM table) AS table".)
 
-=head3 Resultsets
+Under the hood, a source acts as a collection of column definitions. When a
+source feeds into 
+
+=head3 Resultsets (RENAME ME)
 
 The resultset is arguably the single most important breakthrough in DBIx::Class.
 It allows for the gradual building of a SQL statement and reuse of that building
@@ -172,21 +179,18 @@ the others.
 (Expand here, detailing each usage of a resultset and the clauses that each
 uses.)
 
-=head3 Rows
+=head3 Objects (aka, Rows)
 
-Traditionally, the row object is a hashref representing a row in a table. This
-representation is simple to implement, meets the 80/20 case, and completely
-wrong. It fails when dealing with GROUP BY clauses and custom queries. The
-proper treatment of a row object is that it represents the SELECT clause of the
-resultset that generated it. In the 80/20 case, the SELECT clause will be all
-the columns of the primary table being selected. By moving the defintion of the
-row object into the resultset, the row object's definition is closer to its
-usage.
+Traditionally, there is row object is acts as a hashref representing a row in a
+table. This representation is simple to implement, meets the 80/20 case, and is
+completely wrong. It fails when dealing with GROUP BY clauses, custom queries,
+and is generally inflexible.
 
-Under the hood, the row object is defined by using anonymous classes built with
-roles, one role for each column. The roles for the columns are defined in the
-definitions for each table. Those roles flow from the source(s), through the
-resultset and into the row objects.
+DBIx::Class 09 chooses instead to model a row as an object that is a collection
+of columns that contain values. This means that the object is defined by the
+resultset that generates the stream the object comes from. In the standard case,
+the resultset's store is a single table and all columns are selected, acting the
+same way as a DBIx::Class 08 row object would.
 
 =head2 Queries as streams
 
@@ -197,7 +201,7 @@ that memory). Streams, on the other hand, defer loading anything into memory
 until the last possible moment, but are easily convertible into a collection as
 needed. (q.v. Higher Order Perl for more information.)
 
-=head2 
+=head1 EXAMPLES
 
 =head1 TODO