From: Peter Rabbitson <ribasushi@cpan.org>
Date: Sat, 8 Aug 2009 22:23:24 +0000 (+0000)
Subject: Clarify POD and cleanup the ->name-hack warning
X-Git-Tag: v0.08109~29^2~1
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits%2FDBIx-Class.git;a=commitdiff_plain;h=7adc2091aeb552020e572ca5b70808f7e5a27412

Clarify POD and cleanup the ->name-hack warning
---

diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod
index 0951c49..03e6e49 100644
--- a/lib/DBIx/Class/Manual/Cookbook.pod
+++ b/lib/DBIx/Class/Manual/Cookbook.pod
@@ -103,8 +103,9 @@ Sometimes you have to run arbitrary SQL because your query is too complex
 be optimized for your database in a special way, but you still want to
 get the results as a L<DBIx::Class::ResultSet>.
 
-The recommended way to accomplish this is by defining a separate
-L<ResultSource::View|DBIx::Class::ResultSource::View> for your query.
+This is accomplished by defining a
+L<ResultSource::View|DBIx::Class::ResultSource::View> for your query,
+almost like you would define a regular ResultSource.
 
   package My::Schema::Result::UserFriendsComplex;
   use strict;
@@ -116,7 +117,9 @@ L<ResultSource::View|DBIx::Class::ResultSource::View> for your query.
 
   # ->table, ->add_columns, etc.
 
+  # do not attempt to deploy() this view
   __PACKAGE__->result_source_instance->is_virtual(1);
+
   __PACKAGE__->result_source_instance->view_definition(q[
     SELECT u.* FROM user u
     INNER JOIN user_friends f ON u.id = f.user_id
@@ -141,13 +144,21 @@ L</delete>, ...  on it).
 
 Note that you cannot have bind parameters unless is_virtual is set to true.
 
-If you're using the old C<< $rsrc_instance->name(\'( SELECT ...') >> method for
-custom SQL, you are highly encouraged to update your code to use a virtual view
-as above. Otherwise add the following code so that on C<< ->deploy >> there is
-no attempt to create a table with that name:
+=over
+
+=item * NOTE
+
+If you're using the old deprecated C<< $rsrc_instance->name(\'( SELECT ...') >>
+method for custom SQL execution, you are highly encouraged to update your code 
+to use a virtual view as above. If you do not want to change your code, and just
+want to suppress the deprecation warning when you call
+L<DBIx::Class::Schema/deploy>, add this line to your source definition, so that
+C<deploy> will exclude this "table":
 
   sub sqlt_deploy_hook { $_[1]->schema->drop_table ($_[1]) }
 
+=back
+
 =head2 Using specific columns
 
 When you only want specific columns from a table, you can use
diff --git a/lib/SQL/Translator/Parser/DBIx/Class.pm b/lib/SQL/Translator/Parser/DBIx/Class.pm
index 4e57a47..de7c948 100644
--- a/lib/SQL/Translator/Parser/DBIx/Class.pm
+++ b/lib/SQL/Translator/Parser/DBIx/Class.pm
@@ -253,17 +253,19 @@ sub parse {
       $schema->add_table ($tables{$table}{object});
       $tables{$table}{source} -> _invoke_sqlt_deploy_hook( $tables{$table}{object} );
 
-      if ($schema->get_table($table) && $table =~ /SELECT \s+/ix) {
-        warn <<'EOF';
+      # the hook might have already removed the table
+      if ($schema->get_table($table) && $table =~ /^ \s* \( \s* SELECT \s+/ix) {
+        warn <<'EOW';
 
-Custom SQL through ->name(\'( SELECT ...') is DEPRECATED, see the "Arbitrary
-SQL" entry in:
+Custom SQL through ->name(\'( SELECT ...') is DEPRECATED, for more details see
+"Arbitrary SQL through a custom ResultSource" in DBIx::Class::Manual::Cookbook
+or http://search.cpan.org/dist/DBIx-Class/lib/DBIx/Class/Manual/Cookbook.pod
 
-  perldoc DBIx::Class::Manual::Cookbook
+EOW
 
-for the current method of doing this.
-
-EOF
+        # remove the table as there is no way someone might want to
+        # actually deploy this
+        $schema->drop_table ($table);
       }
     }