X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FOptional%2FDependencies.pm;h=37e18c05b8d011221d80486d31ac13724763ef5a;hb=4aa3f96d65ed88da064da2637a42eb76a40452c1;hp=28061598d33fb9f37c3b478cc7d54a7487978ea5;hpb=08ac7648665ed86e88b2a752b31e8a34a8552dc7;p=dbsrgits%2FDBIx-Class-Historic.git

diff --git a/lib/DBIx/Class/Optional/Dependencies.pm b/lib/DBIx/Class/Optional/Dependencies.pm
index 2806159..37e18c0 100644
--- a/lib/DBIx/Class/Optional/Dependencies.pm
+++ b/lib/DBIx/Class/Optional/Dependencies.pm
@@ -3,7 +3,7 @@ package DBIx::Class::Optional::Dependencies;
 use warnings;
 use strict;
 
-use Carp ();
+use Carp;
 
 # NO EXTERNAL NON-5.8.1 CORE DEPENDENCIES EVER (e.g. C::A::G)
 # This module is to be loaded by Makefile.PM on a pristine system
@@ -154,7 +154,7 @@ my $reqs = {
     },
     pod => {
       title => 'Storage::DBI::deploy()',
-      desc => 'Modules required for L<DBIx::Class::Storage::DBI/deploy> and L<DBIx::Class::Storage::DBI/deployment_statements>',
+      desc => 'Modules required for L<DBIx::Class::Storage::DBI/deployment_statements> and L<DBIx::Class::Schema/deploy>',
     },
   },
 
@@ -453,7 +453,6 @@ my $reqs = {
         ? (
           # when changing this list make sure to adjust xt/optional_deps.t
           %$rdbms_pg,
-          ($^O ne 'MSWin32' ? ('Sys::SigAction' => '0') : ()),
           'DBD::Pg'               => '2.009002',
         ) : ()
     },
@@ -622,9 +621,8 @@ my $reqs = {
     req => {
       %$test_and_dist_json_any,
       'ExtUtils::MakeMaker' => '6.64',
-      'Pod::Inherit'        => '0.90',
-      'Pod::Tree'           => '0',
-    }
+      'Pod::Inherit'        => '0.91',
+    },
   },
 
   dist_upload => {
@@ -635,35 +633,44 @@ my $reqs = {
 
 };
 
-our %req_availability_cache;
 
+
+### Public API
+
+# OO for (mistakenly considered) ease of extensibility, not due to any need to
+# carry state of any sort. This API is currently used outside, so leave as-is.
+# FIXME - make sure to not propagate this further if module is extracted as a
+# standalone library - keep the stupidity to a DBIC-secific shim!
+#
 sub req_list_for {
   my ($class, $group) = @_;
 
-  Carp::croak "req_list_for() expects a requirement group name"
+  croak "req_list_for() expects a requirement group name"
     unless $group;
 
   my $deps = $reqs->{$group}{req}
-    or Carp::croak "Requirement group '$group' does not exist";
+    or croak "Requirement group '$group' does not exist";
 
   return { %$deps };
 }
 
+sub req_group_list {
+  return { map { $_ => { %{ $reqs->{$_}{req} || {} } } } (keys %$reqs) };
+}
 
-sub die_unless_req_ok_for {
+sub req_errorlist_for {
   my ($class, $group) = @_;
 
-  Carp::croak "die_unless_req_ok_for() expects a requirement group name"
+  croak "req_errorlist_for() expects a requirement group name"
     unless $group;
 
-  $class->_check_deps($group)->{status}
-    or die sprintf( "Required modules missing, unable to continue: %s\n", $class->_check_deps($group)->{missing} );
+  return $class->_check_deps($group)->{errorlist};
 }
 
 sub req_ok_for {
   my ($class, $group) = @_;
 
-  Carp::croak "req_ok_for() expects a requirement group name"
+  croak "req_ok_for() expects a requirement group name"
     unless $group;
 
   return $class->_check_deps($group)->{status};
@@ -672,21 +679,27 @@ sub req_ok_for {
 sub req_missing_for {
   my ($class, $group) = @_;
 
-  Carp::croak "req_missing_for() expects a requirement group name"
+  croak "req_missing_for() expects a requirement group name"
     unless $group;
 
   return $class->_check_deps($group)->{missing};
 }
 
-sub req_errorlist_for {
+sub die_unless_req_ok_for {
   my ($class, $group) = @_;
 
-  Carp::croak "req_errorlist_for() expects a requirement group name"
+  croak "die_unless_req_ok_for() expects a requirement group name"
     unless $group;
 
-  return $class->_check_deps($group)->{errorlist};
+  $class->_check_deps($group)->{status}
+    or die sprintf( "Required modules missing, unable to continue: %s\n", $class->_check_deps($group)->{missing} );
 }
 
+
+
+### Private API
+
+our %req_availability_cache;
 sub _check_deps {
   my ($class, $group) = @_;
 
@@ -709,8 +722,8 @@ sub _check_deps {
     my $res;
 
     if (keys %errors) {
-      my $missing = join (', ', map { $deps->{$_} ? "$_ >= $deps->{$_}" : $_ } (sort keys %errors) );
-      $missing .= " (see $class for details)" if $reqs->{$group}{pod};
+      my $missing = join (', ', map { $deps->{$_} ? qq("${_}~>=$deps->{$_}") : $_ } (sort keys %errors) );
+      $missing .= " (see $class documentation for details)" if $reqs->{$group}{pod};
       $res = {
         status => 0,
         errorlist => \%errors,
@@ -729,10 +742,6 @@ sub _check_deps {
   };
 }
 
-sub req_group_list {
-  return { map { $_ => { %{ $reqs->{$_}{req} || {} } } } (keys %$reqs) };
-}
-
 # This is to be called by the author only (automatically in Makefile.PL)
 sub _gen_pod {
   my ($class, $distver, $pod_dir) = @_;
@@ -764,7 +773,13 @@ sub _gen_pod {
   my $sqltver = $class->req_list_for ('deploy')->{'SQL::Translator'}
     or die "Hrmm? No sqlt dep?";
 
-  my @chunks = (
+
+  my @chunks;
+
+#@@
+#@@ HEADER
+#@@
+  push @chunks, (
     <<"EOC",
 #########################################################################
 #####################  A U T O G E N E R A T E D ########################
@@ -777,6 +792,13 @@ sub _gen_pod {
 EOC
     '=head1 NAME',
     "$class - Optional module dependency specifications (for module authors)",
+  );
+
+
+#@@
+#@@ SYNOPSIS HEADING
+#@@
+  push @chunks, (
     '=head1 SYNOPSIS',
     <<"EOS",
 Somewhere in your build-file (e.g. L<Module::Install>'s Makefile.PL):
@@ -798,6 +820,13 @@ Somewhere in your build-file (e.g. L<Module::Install>'s Makefile.PL):
 Note that there are some caveats regarding C<configure_requires()>, more info
 can be found at L<Module::Install/configure_requires>
 EOS
+  );
+
+
+#@@
+#@@ DESCRIPTION HEADING
+#@@
+  push @chunks, (
     '=head1 DESCRIPTION',
     <<'EOD',
 Some of the less-frequently used features of L<DBIx::Class> have external
@@ -809,6 +838,13 @@ its operation. This module is the central holding place for  the current list
 of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
 authors alike.
 EOD
+  );
+
+
+#@@
+#@@ REQUIREMENT GROUPLIST HEADING
+#@@
+  push @chunks, (
     '=head1 CURRENT REQUIREMENT GROUPS',
     <<'EOD',
 Dependencies are organized in C<groups> and each group can list one or more
@@ -836,6 +872,10 @@ EOD
     );
   }
 
+
+#@@
+#@@ API DOCUMENTATION HEADING
+#@@
   push @chunks, (
     '=head1 METHODS',
     '=head2 req_group_list',
@@ -885,7 +925,7 @@ be able to use a specific feature.
 For example if some of the requirements for C<deploy> are not available,
 the returned string could look like:
 
- SQL::Translator >= $sqltver (see $class for details)
+ "SQL::Translator~>=$sqltver" (see $class documentation for details)
 
 The author is expected to prepend the necessary text to this message before
 returning the actual error seen by the user.
@@ -910,16 +950,32 @@ EOD
 Returns a hashref containing the actual errors that occurred while attempting
 to load each module in the requirement group.
 EOD
-    '=head1 AUTHOR',
-    'See L<DBIx::Class/CONTRIBUTORS>.',
-    '=head1 LICENSE',
-    'You may distribute this code under the same terms as Perl itself',
   );
 
-  open (my $fh, '>', $podfn) or Carp::croak "Unable to write to $podfn: $!";
-  print $fh join ("\n\n", @chunks);
-  print $fh "\n";
-  close ($fh);
+
+#@@
+#@@ FOOTER
+#@@
+  push @chunks, (
+    '=head1 FURTHER QUESTIONS?',
+    'Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.',
+    '=head1 COPYRIGHT AND LICENSE',
+    <<'EOL',
+This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
+by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
+redistribute it and/or modify it under the same terms as the
+L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
+EOL
+
+  );
+
+
+  eval {
+    open (my $fh, '>', $podfn) or die;
+    print $fh join ("\n\n", @chunks) or die;
+    print $fh "\n" or die;
+    close ($fh) or die;
+  } or croak( "Unable to write $podfn: " . ( $! || $@ || 'unknown error') );
 }
 
 1;