Added use strict / use warnings everywhere it was missing

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Schema.pm

diff --git a/lib/DBIx/Class/Schema.pm b/lib/DBIx/Class/Schema.pm
index 19b49c3..3d63657 100644 (file)
--- a/lib/DBIx/Class/Schema.pm
+++ b/lib/DBIx/Class/Schema.pm
@@ -26,7 +26,7 @@ DBIx::Class::Schema - composable schemas
 
   package Library::Schema::CD;
   use base qw/DBIx::Class/;
-  __PACKAGE__->load_components(qw/PK::Auto::Pg Core/); # for example
+  __PACKAGE__->load_components(qw/PK::Auto Core/); # for example
   __PACKAGE__->table('cd');
 
   # Elsewhere in your code:
@@ -149,7 +149,7 @@ sub resultset {
 
 =head2 load_classes
 
-=head3 Arguments: [<classes>, (<class>, <class>), {<namespace> => [<classes>]}]
+=head3 Arguments: @classes?, { $namespace => [ $class+ ] }+
 
 Uses L<Module::Find> to find all classes under the database class' namespace,
 or uses the classes you select.  Then it loads the component (using L<use>), 
@@ -190,9 +190,11 @@ sub load_classes {
     }
   } else {
     eval "require Module::Find;";
-    $class->throw_exception("No arguments to load_classes and couldn't load".
-      " Module::Find ($@)") if $@;
-    my @comp = map { substr $_, length "${class}::"  } Module::Find::findallmod($class);
+    $class->throw_exception(
+      "No arguments to load_classes and couldn't load Module::Find ($@)"
+    ) if $@;
+    my @comp = map { substr $_, length "${class}::"  }
+                 Module::Find::findallmod($class);
     $comps_for{$class} = \@comp;
   }
 
@@ -223,27 +225,16 @@ sub load_classes {
 
 =head2 compose_connection
 
-=head3 Arguments: <target> <@db_info>
+=head3 Arguments: $target_ns, @db_info
 
-This is the most important method in this class. it takes a target namespace,
-as well as dbh connection info, and creates a L<DBIx::Class::DB> class as
-well as subclasses for each of your database classes in this namespace, using
-this connection.
+=head3 Return value: $new_schema
 
-It will also setup a ->class method on the target class, which lets you
-resolve database classes based on the schema component name, for example
-
-  Library::Model::DB->class('Book') # returns Library::Model::Book, 
-                                    # which ISA Library::Schema::Book
-
-This is the recommended API for accessing Schema generated classes, and 
-using it might give you instant advantages with future versions of DBIC.
-
-WARNING: Loading components into Schema classes after compose_connection
-may not cause them to be seen by the classes in your target namespace due
-to the dispatch table approach used by Class::C3. If you do this you may find
-you need to call Class::C3->reinitialize() afterwards to get the behaviour
-you expect.
+Calls compose_namespace to the $target_ns, calls ->connection(@db_info) on
+the new schema, then injects the ResultSetProxy component and a
+resultset_instance classdata entry on all the new classes in order to support
+$target_ns::Class->search(...) method calls. Primarily useful when you have
+a specific need for classmethod access to a connection - in normal usage
+->connect is preferred.
 
 =cut
 
@@ -251,8 +242,9 @@ sub compose_connection {
   my ($self, $target, @info) = @_;
   my $base = 'DBIx::Class::ResultSetProxy';
   eval "require ${base};";
-  $self->throw_exception("No arguments to load_classes and couldn't load".
-      " ${base} ($@)") if $@;
+  $self->throw_exception
+    ("No arguments to load_classes and couldn't load ${base} ($@)")
+      if $@;
 
   if ($self eq $target) {
     # Pathological case, largely caused by the docs on early C::M::DBIC::Plain
@@ -285,6 +277,21 @@ sub compose_connection {
   return $schema;
 }
 
+=head2 compose_namespace
+
+=head3 Arguments: $target_ns, $additional_base_class?
+
+=head3 Return value: $new_schema
+
+For each result source in the schema, creates a class in the target
+namespace (e.g. $target_ns::CD, $target_ns::Artist) inheriting from the
+corresponding classes attached to the current schema and a result source
+to match attached to the new $schema object. If an additional base class is
+given, injects this immediately behind the corresponding classes from the
+current schema in the created classes' @ISA.
+
+=cut
+
 sub compose_namespace {
   my ($self, $target, $base) = @_;
   my %reg = %{ $self->source_registrations };
@@ -347,8 +354,9 @@ sub connection {
   $storage_class = 'DBIx::Class::Storage'.$storage_class
     if $storage_class =~ m/^::/;
   eval "require ${storage_class};";
-  $self->throw_exception("No arguments to load_classes and couldn't load".
-      " ${storage_class} ($@)") if $@;
+  $self->throw_exception(
+    "No arguments to load_classes and couldn't load ${storage_class} ($@)"
+  ) if $@;
   my $storage = $storage_class->new;
   $storage->connect_info(\@info);
   $self->storage($storage);
@@ -391,7 +399,7 @@ sub txn_rollback { shift->storage->txn_rollback }
 
 =head2 txn_do
 
-=head3 Arguments: <$coderef>, [@coderef_args]
+=head3 Arguments: $coderef, @coderef_args?
 
 Executes C<$coderef> with (optional) arguments C<@coderef_args>
 transactionally, returning its result (if any). If an exception is
@@ -447,7 +455,9 @@ sub txn_do {
 
   $self->txn_begin; # If this throws an exception, no rollback is needed
 
-  my $wantarray = wantarray; # Need to save this since it's reset in eval{}
+  my $wantarray = wantarray; # Need to save this since the context
+                            # inside the eval{} block is independent
+                            # of the context that called txn_do()
 
   eval {
     # Need to differentiate between scalar/list context to allow for
@@ -479,8 +489,9 @@ sub txn_do {
       $self->throw_exception($error)  # propagate nested rollback
        if $rollback_error =~ /$exception_class/;
 
-      $self->throw_exception("Transaction aborted: $error. Rollback failed: ".
-                             $rollback_error);
+      $self->throw_exception(
+        "Transaction aborted: $error. Rollback failed: ${rollback_error}"
+      );
     } else {
       $self->throw_exception($error); # txn failed but rollback succeeded
     }