lib/DBIx/Class/Optional/Dependencies.pm

   1 package DBIx::Class::Optional::Dependencies;
   2
   3 use warnings;
   4 use strict;
   5
   6 use Carp;
   7
   8 # NO EXTERNAL NON-5.8.1 CORE DEPENDENCIES EVER (e.g. C::A::G)
   9 # This module is to be loaded by Makefile.PM on a pristine system
  10
  11 # POD is generated automatically by calling _gen_pod from the
  12 # Makefile.PL in $AUTHOR mode
  13
  14 my $moose_basic = {
  15   'Moose'                      => '0.98',
  16   'MooseX::Types'              => '0.21',
  17 };
  18
  19 my $admin_basic = {
  20   %$moose_basic,
  21   'MooseX::Types::Path::Class' => '0.05',
  22   'MooseX::Types::JSON'        => '0.02',
  23   'namespace::autoclean'       => '0.09',
  24   'parent'                     => '0.223',
  25 };
  26
  27 my $reqs = {
  28   dist => {
  29     #'Module::Install::Pod::Inherit' => '0.01',
  30   },
  31
  32   replicated => {
  33     req => {
  34       %$moose_basic,
  35       'namespace::clean'          => '0.11',
  36       'Hash::Merge'               => '0.11',
  37     },
  38     pod => {
  39       title => 'Storage::Replicated',
  40       desc => 'Modules required for L<DBIx::Class::Storage::DBI::Replicated>',
  41     },
  42   },
  43
  44   admin => {
  45     req => {
  46       %$admin_basic,
  47     },
  48     pod => {
  49       title => 'DBIx::Class::Admin',
  50       desc => 'Modules required for the DBIx::Class administrative library',
  51     },
  52   },
  53
  54   admin_script => {
  55     req => {
  56       %$moose_basic,
  57       %$admin_basic,
  58       'Getopt::Long::Descriptive' => '0.081',
  59       'JSON::Any'                 => '1.22',
  60       'Text::CSV'                 => '1.16',
  61     },
  62     pod => {
  63       title => 'dbicadmin',
  64       desc => 'Modules required for the CLI DBIx::Class interface dbicadmin',
  65     },
  66   },
  67
  68   deploy => {
  69     req => {
  70       'SQL::Translator'           => '0.11002',
  71     },
  72     pod => {
  73       title => 'Storage::DBI::deploy()',
  74       desc => 'Modules required for L<DBIx::Class::Storage::DBI/deploy> and L<DBIx::Class::Storage::DBI/deploymen_statements>',
  75     },
  76   },
  77
  78   author => {
  79     req => {
  80       'Test::Pod'                 => '1.26',
  81       'Test::Pod::Coverage'       => '1.08',
  82       'Pod::Coverage'             => '0.20',
  83       #'Test::NoTabs'              => '0.9',
  84       #'Test::EOL'                 => '0.6',
  85     },
  86   },
  87
  88   core => {
  89     req => {
  90       # t/52cycle.t
  91       'Test::Memory::Cycle'       => '0',
  92       'Devel::Cycle'              => '1.10',
  93
  94       # t/36datetime.t
  95       # t/60core.t
  96       'DateTime::Format::SQLite'  => '0',
  97
  98       # t/96_is_deteministic_value.t
  99       'DateTime::Format::Strptime'=> '0',
 100     },
 101   },
 102
 103   cdbicompat => {
 104     req => {
 105       'DBIx::ContextualFetch'     => '0',
 106       'Class::DBI::Plugin::DeepAbstractSearch' => '0',
 107       'Class::Trigger'            => '0',
 108       'Time::Piece::MySQL'        => '0',
 109       'Clone'                     => '0',
 110       'Date::Simple'              => '3.03',
 111     },
 112   },
 113
 114   rdbms_pg => {
 115     req => {
 116       $ENV{DBICTEST_PG_DSN}
 117         ? (
 118           'Sys::SigAction'        => '0',
 119           'DBD::Pg'               => '2.009002',
 120           'DateTime::Format::Pg'  => '0',
 121         ) : ()
 122     },
 123   },
 124
 125   rdbms_mysql => {
 126     req => {
 127       $ENV{DBICTEST_MYSQL_DSN}
 128         ? (
 129           'DateTime::Format::MySQL' => '0',
 130           'DBD::mysql'              => '0',
 131         ) : ()
 132     },
 133   },
 134
 135   rdbms_oracle => {
 136     req => {
 137       $ENV{DBICTEST_ORA_DSN}
 138         ? (
 139           'DateTime::Format::Oracle' => '0',
 140         ) : ()
 141     },
 142   },
 143
 144   rdbms_ase => {
 145     req => {
 146       $ENV{DBICTEST_SYBASE_DSN}
 147         ? (
 148           'DateTime::Format::Sybase' => 0,
 149         ) : ()
 150     },
 151   },
 152
 153   rdbms_asa => {
 154     req => {
 155       grep $_, @ENV{qw/DBICTEST_SYBASE_ASA_DSN DBICTEST_SYBASE_ASA_ODBC_DSN/}
 156         ? (
 157           'DateTime::Format::Strptime' => 0,
 158         ) : ()
 159     },
 160   },
 161 };
 162
 163
 164 sub _all_optional_requirements {
 165   return { map { %{ $reqs->{$_}{req} || {} } } (keys %$reqs) };
 166 }
 167
 168 sub req_list_for {
 169   my ($class, $group) = @_;
 170
 171   croak "req_list_for() expects a requirement group name"
 172     unless $group;
 173
 174   my $deps = $reqs->{$group}{req}
 175     or croak "Requirement group '$group' does not exist";
 176
 177   return { %$deps };
 178 }
 179
 180
 181 our %req_availability_cache;
 182 sub req_ok_for {
 183   my ($class, $group) = @_;
 184
 185   croak "req_ok_for() expects a requirement group name"
 186     unless $group;
 187
 188   $class->_check_deps ($group) unless $req_availability_cache{$group};
 189
 190   return $req_availability_cache{$group}{status};
 191 }
 192
 193 sub req_missing_for {
 194   my ($class, $group) = @_;
 195
 196   croak "req_missing_for() expects a requirement group name"
 197     unless $group;
 198
 199   $class->_check_deps ($group) unless $req_availability_cache{$group};
 200
 201   return $req_availability_cache{$group}{missing};
 202 }
 203
 204 sub req_errorlist_for {
 205   my ($class, $group) = @_;
 206
 207   croak "req_errorlist_for() expects a requirement group name"
 208     unless $group;
 209
 210   $class->_check_deps ($group) unless $req_availability_cache{$group};
 211
 212   return $req_availability_cache{$group}{errorlist};
 213 }
 214
 215 sub _check_deps {
 216   my ($class, $group) = @_;
 217
 218   my $deps = $class->req_list_for ($group);
 219
 220   my %errors;
 221   for my $mod (keys %$deps) {
 222     if (my $ver = $deps->{$mod}) {
 223       eval "use $mod $ver ()";
 224     }
 225     else {
 226       eval "require $mod";
 227     }
 228
 229     $errors{$mod} = $@ if $@;
 230   }
 231
 232   if (keys %errors) {
 233     my $missing = join (', ', map { $deps->{$_} ? "$_ >= $deps->{$_}" : $_ } (sort keys %errors) );
 234     $missing .= " (see $class for details)" if $reqs->{$group}{pod};
 235     $req_availability_cache{$group} = {
 236       status => 0,
 237       errorlist => { %errors },
 238       missing => $missing,
 239     };
 240   }
 241   else {
 242     $req_availability_cache{$group} = {
 243       status => 1,
 244       errorlist => {},
 245       missing => '',
 246     };
 247   }
 248 }
 249
 250 sub _gen_pod {
 251   my $class = shift;
 252
 253   my @chunks = (
 254     '=head1 NAME',
 255     "$class - Optional module dependency specifications",
 256     '=head1 DESCRIPTION',
 257     <<'EOD',
 258 Some of the less-frequently used features of L<DBIx::Class> have external
 259 module dependencies on their own. In order not to burden the average user
 260 with modules he will never use, these optional dependencies are not included
 261 in the base Makefile.PL. Instead an exception with a descriptive message is
 262 thrown when a specific feature is missing one or several modules required for
 263 its operation. This module is the central holding place for  the current list
 264 of such dependencies.
 265 EOD
 266     '=head1 CURRENT REQUIREMENT GROUPS',
 267     <<'EOD',
 268 Dependencies are organized in C<groups> and each group can list one or more
 269 required modules, with an optional minimum version (or 0 for any version).
 270 The group name can be used in the
 271 EOD
 272   );
 273
 274   for my $group (sort keys %$reqs) {
 275     my $p = $reqs->{$group}{pod}
 276       or next;
 277
 278     my $modlist = $reqs->{$group}{req}
 279       or next;
 280
 281     next unless keys %$modlist;
 282
 283     push @chunks, (
 284       "=head2 $p->{title}",
 285       "$p->{desc}",
 286       '=over',
 287       ( map { "=item * $_" . ($modlist->{$_} ? " >= $modlist->{$_}" : '') } (sort keys %$modlist) ),
 288       '=back',
 289       "Requirement group: B<$group>",
 290     );
 291   }
 292
 293   push @chunks, (
 294     '=head1 METHODS',
 295     '=head2 req_list_for',
 296     '=over',
 297     '=item Arguments: $group_name',
 298     '=item Returns: \%list_of_module_version_pairs',
 299     '=back',
 300     <<EOD,
 301 This method should be used by DBIx::Class extension authors, to determine the
 302 version of modules which a specific feature requires in the current version of
 303 DBIx::Class. For example if you write a module/extension that requires
 304 DBIx::Class and also requires the availability of
 305 L<DBIx::Class::Storage::DBI/deploy>, you can do the following in your
 306 C<Makefile.PL> or C<Build.PL>
 307
 308  require $class;
 309  my \$dep_list = $class->req_list_for ('deploy');
 310
 311 Which will give you a list of module/version pairs necessary for the particular
 312 feature to function with this version of DBIx::Class.
 313 EOD
 314
 315     '=head2 req_ok_for',
 316     '=over',
 317     '=item Arguments: $group_name',
 318     '=item Returns: 1|0',
 319     '=back',
 320     'Returns true or false depending on whether all modules required by $group_name are present on the system and loadable',
 321
 322     '=head2 req_missing_for',
 323     '=over',
 324     '=item Arguments: $group_name',
 325     '=item Returns: $error_message_string',
 326     '=back',
 327     <<EOD,
 328 Returns a single line string suitable for inclusion in larger error messages.
 329 This method would normally be used by DBIx::Class core-module author, to
 330 indicate to the user that he needs to install specific modules before he will
 331 be able to use a specific feature.
 332
 333 For example if the requirements for C<replicated> are not available, the
 334 returned string would look like:
 335
 336  Moose >= 0.98, MooseX::Types >= 0.21, namespace::clean (see $class for details)
 337
 338 The author is expected to prepend the necessary text to this message before
 339 returning the actual error seen by the user.
 340 EOD
 341
 342     '=head2 req_errorlist_for',
 343     '=over',
 344     '=item Arguments: $group_name',
 345     '=item Returns: \%list_of_loaderrors_per_module',
 346     '=back',
 347     <<'EOD',
 348 Returns a hashref containing the actual errors that occured while attempting
 349 to load each module in the requirement group.
 350 EOD
 351
 352   );
 353
 354   my $fn = __FILE__;
 355   $fn =~ s/\.pm$/\.pod/;
 356
 357   open (my $fh, '>', $fn) or croak "Unable to write to $fn: $!";
 358   print $fh join ("\n\n", @chunks);
 359   close ($fh);
 360 }
 361
 362 1;