Neither of these can fail now that we dep on 5.8.1 (missed in 55087b99)

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Optional / Dependencies.pm

diff --git a/lib/DBIx/Class/Optional/Dependencies.pm b/lib/DBIx/Class/Optional/Dependencies.pm
index 27d3817..37e18c0 100644 (file)
--- a/lib/DBIx/Class/Optional/Dependencies.pm
+++ b/lib/DBIx/Class/Optional/Dependencies.pm
@@ -633,8 +633,15 @@ 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) = @_;
 
@@ -647,15 +654,17 @@ sub req_list_for {
   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) = @_;
 
-  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 {
@@ -676,15 +685,21 @@ sub req_missing_for {
   return $class->_check_deps($group)->{missing};
 }
 
-sub req_errorlist_for {
+sub die_unless_req_ok_for {
   my ($class, $group) = @_;
 
-  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) = @_;
 
@@ -707,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,
@@ -727,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) = @_;
@@ -762,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 ########################
@@ -775,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):
@@ -796,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
@@ -807,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
@@ -834,6 +872,10 @@ EOD
     );
   }
 
+
+#@@
+#@@ API DOCUMENTATION HEADING
+#@@
   push @chunks, (
     '=head1 METHODS',
     '=head2 req_group_list',
@@ -883,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.
@@ -908,6 +950,13 @@ EOD
 Returns a hashref containing the actual errors that occurred while attempting
 to load each module in the requirement group.
 EOD
+  );
+
+
+#@@
+#@@ FOOTER
+#@@
+  push @chunks, (
     '=head1 FURTHER QUESTIONS?',
     'Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.',
     '=head1 COPYRIGHT AND LICENSE',
@@ -920,6 +969,7 @@ EOL
 
   );
 
+
   eval {
     open (my $fh, '>', $podfn) or die;
     print $fh join ("\n\n", @chunks) or die;