From: Rob Kinyon <rkinyon@rkinyon-lt-osx.local>
Date: Wed, 19 Aug 2009 18:19:02 +0000 (-0400)
Subject: Added commands and API sketch
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=refs%2Fheads%2Fmaster;p=dbsrgits%2Fdbic-future.git

Added commands and API sketch
---

diff --git a/lib/DBIx/Class/Manual/Store.pm b/lib/DBIx/Class/Manual/Store.pm
index 5d31515..f7d7c9e 100644
--- a/lib/DBIx/Class/Manual/Store.pm
+++ b/lib/DBIx/Class/Manual/Store.pm
@@ -1,6 +1,6 @@
 =head1 NAME
 
-DBIx::Class::Manual::Storage
+DBIx::Class::Manual::Store
 
 =head1 SYNOPSIS
 
@@ -25,7 +25,6 @@ as a Collection of Types (or Collection[Types]).
 From the client code perspective, there is one virtual store which provides an
 abstraction around the concrete stores which map to physical datastores.
 
-
 =head1 SUPPORTED DATASTORES
 
 =head2 Relational databases
@@ -59,6 +58,61 @@ treated as such. Otherwise, it acts as a DocDB and should be treated as such.
 
 Fill me in here.
 
+=head1 API
+
+The API for a Store breaks into two parts. The first set of methods are
+transformative - they clone the existing store, modify the clone, and return it.
+The second set are commands - they clone the existing store and return a command
+that operates on that clone. In all cases, the existing store (the invocant) is
+B<NOT> changed in any way.
+
+=head2 TRANSFORMATIVE METHODS
+
+=head3 $store->combine( $other_store, [ $args ] )
+
+This takes two stores and provides a store that provides a search across both.
+In other words, it acts as a JOIN in SQL. The optional C< $args > may be
+specified to provide join conditions (such as ON in SQL).
+
+$other_store is mandatory. $args is optional and store-dependent.
+
+=head3 $store->project( $args )
+
+This will determine the available values for reading off the stream should this
+store have a Command::Query build off of it. The project values default to '*',
+or all available values from the store(s) used as the basis. This corresponds to
+the SELECT clause of a SQL statement.
+
+$args is mandatory and store-dependent.
+
+=head3 $store->fold( $args )
+
+This will allow the use of aggregation functions by specifying which values are
+to be pivoted on when aggregating. This corresponds to the GROUP BY clause of a
+SQL statement.
+
+$args is mandatory and store-dependent.
+
+=head2 COMMAND METHODS
+
+For the Command API, please see L<DBIx::Class::Store::Command/>.
+
+=head3 $store->query_command()
+
+This returns a Command::Query object.
+
+=head3 $store->insert_command()
+
+This returns a Command::Insert object.
+
+=head3 $store->update_command()
+
+This returns a Command::Update object.
+
+=head3 $store->delete_command()
+
+This returns a Command::Delete object.
+
 =head1 TODO
 
 =over 4
diff --git a/lib/DBIx/Class/Manual/Store/Command.pm b/lib/DBIx/Class/Manual/Store/Command.pm
new file mode 100644
index 0000000..e08872f
--- /dev/null
+++ b/lib/DBIx/Class/Manual/Store/Command.pm
@@ -0,0 +1,44 @@
+=head1 NAME
+
+DBIx::Class::Manual::Store::Command
+
+=head1 SYNOPSIS
+
+This document details how the Data::Store::Command works.
+
+=head1 EXAMPLES
+
+  Fill me in here
+
+=head1 OVERVIEW
+
+Data::Store::Command is a set of commands that operate on Data::Store objects.
+They allow for various data stores to spawn off commands that can be modified
+prior to being executed.
+
+=head1 METHODS
+
+All commands provide the following method. Each will have additional commands
+specific to itself.
+
+=head2 $command->execute()
+
+Executes the command.
+
+=head1 TODO
+
+=over 4
+
+=item * Add EXAMPLES
+
+=back
+
+=head1 AUTHOR(S)
+
+robkinyon: Rob Kinyon C<< <rkinyon@cpan.org> >>
+
+=head1 LICENSE
+
+You may distribute this code under the same terms as Perl itself.
+
+=cut