lib/DBIx/Class/Optional/Dependencies.pm

   1 package DBIx::Class::Optional::Dependencies;
   2
   3 ### This may look crazy, but it in fact tangibly ( by 50(!)% ) shortens
   4 #   the skip-test time when everything requested is unavailable
   5 use if $ENV{RELEASE_TESTING} => 'warnings';
   6 use if $ENV{RELEASE_TESTING} => 'strict';
   7
   8 sub croak {
   9   require Carp;
  10   Carp::croak(@_);
  11 };
  12 ###
  13
  14 # NO EXTERNAL NON-5.8.1 CORE DEPENDENCIES EVER (e.g. C::A::G)
  15 # This module is to be loaded by Makefile.PM on a pristine system
  16
  17 # POD is generated automatically by calling _gen_pod from the
  18 # Makefile.PL in $AUTHOR mode
  19
  20 # NOTE: the rationale for 2 JSON::Any versions is that
  21 # we need the newer only to work around JSON::XS, which
  22 # itself is an optional dep
  23 my $min_json_any = {
  24   'JSON::Any'                     => '1.23',
  25 };
  26 my $test_and_dist_json_any = {
  27   'JSON::Any'                     => '1.31',
  28 };
  29
  30 my $moose_basic = {
  31   'Moose'                         => '0.98',
  32   'MooseX::Types'                 => '0.21',
  33   'MooseX::Types::LoadableClass'  => '0.011',
  34 };
  35
  36 my $dbic_reqs = {
  37   replicated => {
  38     req => $moose_basic,
  39     pod => {
  40       title => 'Storage::Replicated',
  41       desc => 'Modules required for L<DBIx::Class::Storage::DBI::Replicated>',
  42     },
  43   },
  44
  45   test_replicated => {
  46     include => 'replicated',
  47     req => {
  48       'Test::Moose' => '0',
  49     },
  50   },
  51
  52   admin => {
  53     req => {
  54       %$moose_basic,
  55       %$min_json_any,
  56       'MooseX::Types::Path::Class' => '0.05',
  57       'MooseX::Types::JSON' => '0.02',
  58     },
  59     pod => {
  60       title => 'DBIx::Class::Admin',
  61       desc => 'Modules required for the DBIx::Class administrative library',
  62     },
  63   },
  64
  65   admin_script => {
  66     include => 'admin',
  67     req => {
  68       'Getopt::Long::Descriptive' => '0.081',
  69       'Text::CSV' => '1.16',
  70     },
  71     pod => {
  72       title => 'dbicadmin',
  73       desc => 'Modules required for the CLI DBIx::Class interface dbicadmin',
  74     },
  75   },
  76
  77   deploy => {
  78     req => {
  79       'SQL::Translator'           => '0.11018',
  80     },
  81     pod => {
  82       title => 'Storage::DBI::deploy()',
  83       desc => 'Modules required for L<DBIx::Class::Storage::DBI/deployment_statements> and L<DBIx::Class::Schema/deploy>',
  84     },
  85   },
  86
  87   id_shortener => {
  88     req => {
  89       'Math::BigInt' => '1.80',
  90       'Math::Base36' => '0.07',
  91     },
  92   },
  93
  94   test_component_accessor => {
  95     req => {
  96       'Class::Unload'             => '0.07',
  97     },
  98   },
  99
 100   test_pod => {
 101     req => {
 102       'Test::Pod'                 => '1.42',
 103     },
 104     release_testing_mandatory => 1,
 105   },
 106
 107   test_podcoverage => {
 108     req => {
 109       'Test::Pod::Coverage'       => '1.08',
 110       'Pod::Coverage'             => '0.20',
 111     },
 112     release_testing_mandatory => 1,
 113   },
 114
 115   test_whitespace => {
 116     req => {
 117       'Test::EOL'                 => '1.0',
 118       'Test::NoTabs'              => '0.9',
 119     },
 120     release_testing_mandatory => 1,
 121   },
 122
 123   test_strictures => {
 124     req => {
 125       'Test::Strict'              => '0.20',
 126     },
 127     release_testing_mandatory => 1,
 128   },
 129
 130   test_prettydebug => {
 131     req => $min_json_any,
 132   },
 133
 134   test_admin_script => {
 135     include => 'admin_script',
 136     req => {
 137       %$test_and_dist_json_any,
 138       'JSON' => 0,
 139       'JSON::PP' => 0,
 140       'Cpanel::JSON::XS' => 0,
 141       'JSON::XS' => 0,
 142       $^O eq 'MSWin32'
 143         # for t/admin/10script.t
 144         ? ('Win32::ShellQuote' => 0)
 145         # DWIW does not compile (./configure even) on win32
 146         : ('JSON::DWIW' => 0 )
 147       ,
 148     }
 149   },
 150
 151   test_leaks_heavy => {
 152     req => {
 153       'Class::MethodCache' => '0.02',
 154       'PadWalker' => '1.06',
 155     },
 156   },
 157
 158   test_dt => {
 159     req => {
 160       'DateTime'                    => '0.55',
 161       'DateTime::Format::Strptime'  => '1.2',
 162     },
 163   },
 164
 165   test_dt_sqlite => {
 166     include => 'test_dt',
 167     req => {
 168       # t/36datetime.t
 169       # t/60core.t
 170       'DateTime::Format::SQLite'  => '0',
 171     },
 172   },
 173
 174   test_dt_mysql => {
 175     include => 'test_dt',
 176     req => {
 177       # t/inflate/datetime_mysql.t
 178       # (doesn't need Mysql itself)
 179       'DateTime::Format::MySQL'   => '0',
 180     },
 181   },
 182
 183   test_dt_pg => {
 184     include => 'test_dt',
 185     req => {
 186       # t/inflate/datetime_pg.t
 187       # (doesn't need PG itself)
 188       'DateTime::Format::Pg'      => '0.16004',
 189     },
 190   },
 191
 192   test_cdbicompat => {
 193     include => 'test_dt',
 194     req => {
 195       'Class::DBI::Plugin::DeepAbstractSearch' => '0',
 196       'Time::Piece::MySQL'        => '0',
 197       'Date::Simple'              => '3.03',
 198     },
 199   },
 200
 201   rdbms_generic_odbc => {
 202     req => {
 203       'DBD::ODBC' => 0,
 204     }
 205   },
 206
 207   rdbms_generic_ado => {
 208     req => {
 209       'DBD::ADO' => 0,
 210     }
 211   },
 212
 213   # this is just for completeness as SQLite
 214   # is a core dep of DBIC for testing
 215   rdbms_sqlite => {
 216     req => {
 217       'DBD::SQLite' => 0,
 218     },
 219     pod => {
 220       title => 'SQLite support',
 221       desc => 'Modules required to connect to SQLite',
 222     },
 223   },
 224
 225   rdbms_pg => {
 226     req => {
 227       # when changing this list make sure to adjust xt/optional_deps.t
 228       'DBD::Pg' => 0,
 229     },
 230     pod => {
 231       title => 'PostgreSQL support',
 232       desc => 'Modules required to connect to PostgreSQL',
 233     },
 234   },
 235
 236   rdbms_mssql_odbc => {
 237     include => 'rdbms_generic_odbc',
 238     pod => {
 239       title => 'MSSQL support via DBD::ODBC',
 240       desc => 'Modules required to connect to MSSQL via DBD::ODBC',
 241     },
 242   },
 243
 244   rdbms_mssql_sybase => {
 245     req => {
 246       'DBD::Sybase' => 0,
 247     },
 248     pod => {
 249       title => 'MSSQL support via DBD::Sybase',
 250       desc => 'Modules required to connect to MSSQL via DBD::Sybase',
 251     },
 252   },
 253
 254   rdbms_mssql_ado => {
 255     include => 'rdbms_generic_ado',
 256     pod => {
 257       title => 'MSSQL support via DBD::ADO (Windows only)',
 258       desc => 'Modules required to connect to MSSQL via DBD::ADO. This particular DBD is available on Windows only',
 259     },
 260   },
 261
 262   rdbms_msaccess_odbc => {
 263     include => 'rdbms_generic_odbc',
 264     pod => {
 265       title => 'MS Access support via DBD::ODBC',
 266       desc => 'Modules required to connect to MS Access via DBD::ODBC',
 267     },
 268   },
 269
 270   rdbms_msaccess_ado => {
 271     include => 'rdbms_generic_ado',
 272     pod => {
 273       title => 'MS Access support via DBD::ADO (Windows only)',
 274       desc => 'Modules required to connect to MS Access via DBD::ADO. This particular DBD is available on Windows only',
 275     },
 276   },
 277
 278   rdbms_mysql => {
 279     req => {
 280       'DBD::mysql' => 0,
 281     },
 282     pod => {
 283       title => 'MySQL support',
 284       desc => 'Modules required to connect to MySQL',
 285     },
 286   },
 287
 288   rdbms_oracle => {
 289     include => 'id_shortener',
 290     req => {
 291       'DBD::Oracle' => 0,
 292     },
 293     pod => {
 294       title => 'Oracle support',
 295       desc => 'Modules required to connect to Oracle',
 296     },
 297   },
 298
 299   rdbms_ase => {
 300     req => {
 301       'DBD::Sybase' => 0,
 302     },
 303     pod => {
 304       title => 'Sybase ASE support',
 305       desc => 'Modules required to connect to Sybase ASE',
 306     },
 307   },
 308
 309   rdbms_db2 => {
 310     req => {
 311       'DBD::DB2' => 0,
 312     },
 313     pod => {
 314       title => 'DB2 support',
 315       desc => 'Modules required to connect to DB2',
 316     },
 317   },
 318
 319   rdbms_db2_400 => {
 320     include => 'rdbms_generic_odbc',
 321     pod => {
 322       title => 'DB2 on AS/400 support',
 323       desc => 'Modules required to connect to DB2 on AS/400',
 324     },
 325   },
 326
 327   rdbms_informix => {
 328     req => {
 329       'DBD::Informix' => 0,
 330     },
 331     pod => {
 332       title => 'Informix support',
 333       desc => 'Modules required to connect to Informix',
 334     },
 335   },
 336
 337   rdbms_sqlanywhere => {
 338     req => {
 339       'DBD::SQLAnywhere' => 0,
 340     },
 341     pod => {
 342       title => 'SQLAnywhere support',
 343       desc => 'Modules required to connect to SQLAnywhere',
 344     },
 345   },
 346
 347   rdbms_sqlanywhere_odbc => {
 348     include => 'rdbms_generic_odbc',
 349     pod => {
 350       title => 'SQLAnywhere support via DBD::ODBC',
 351       desc => 'Modules required to connect to SQLAnywhere via DBD::ODBC',
 352     },
 353   },
 354
 355   rdbms_firebird => {
 356     req => {
 357       'DBD::Firebird' => 0,
 358     },
 359     pod => {
 360       title => 'Firebird support',
 361       desc => 'Modules required to connect to Firebird',
 362     },
 363   },
 364
 365   rdbms_firebird_interbase => {
 366     req => {
 367       'DBD::InterBase' => 0,
 368     },
 369     pod => {
 370       title => 'Firebird support via DBD::InterBase',
 371       desc => 'Modules required to connect to Firebird via DBD::InterBase',
 372     },
 373   },
 374
 375   rdbms_firebird_odbc => {
 376     include => 'rdbms_generic_odbc',
 377     pod => {
 378       title => 'Firebird support via DBD::ODBC',
 379       desc => 'Modules required to connect to Firebird via DBD::ODBC',
 380     },
 381   },
 382
 383   test_rdbms_sqlite => {
 384     include => 'rdbms_sqlite',
 385     req => {
 386       ###
 387       ### IMPORTANT - do not raise this dependency
 388       ### even though many bugfixes are present in newer versions, the general DBIC
 389       ### rule is to bend over backwards for available DBDs (given upgrading them is
 390       ### often *not* easy or even possible)
 391       ###
 392       'DBD::SQLite' => '1.29',
 393     },
 394   },
 395
 396   test_rdbms_pg => {
 397     include => 'rdbms_pg',
 398     env => [
 399       DBICTEST_PG_DSN => 1,
 400       DBICTEST_PG_USER => 0,
 401       DBICTEST_PG_PASS => 0,
 402     ],
 403     req => {
 404       # the order does matter because the rdbms support group might require
 405       # a different version that the test group
 406       #
 407       # when changing this list make sure to adjust xt/optional_deps.t
 408       'DBD::Pg' => '2.009002',  # specific version to test bytea
 409     },
 410   },
 411
 412   test_rdbms_mssql_odbc => {
 413     include => 'rdbms_mssql_odbc',
 414     env => [
 415       DBICTEST_MSSQL_ODBC_DSN => 1,
 416       DBICTEST_MSSQL_ODBC_USER => 0,
 417       DBICTEST_MSSQL_ODBC_PASS => 0,
 418     ],
 419   },
 420
 421   test_rdbms_mssql_ado => {
 422     include => 'rdbms_mssql_ado',
 423     env => [
 424       DBICTEST_MSSQL_ADO_DSN => 1,
 425       DBICTEST_MSSQL_ADO_USER => 0,
 426       DBICTEST_MSSQL_ADO_PASS => 0,
 427     ],
 428   },
 429
 430   test_rdbms_mssql_sybase => {
 431     include => 'rdbms_mssql_sybase',
 432     env => [
 433       DBICTEST_MSSQL_DSN => 1,
 434       DBICTEST_MSSQL_USER => 0,
 435       DBICTEST_MSSQL_PASS => 0,
 436     ],
 437   },
 438
 439   test_rdbms_msaccess_odbc => {
 440     include => 'rdbms_msaccess_odbc',
 441     env => [
 442       DBICTEST_MSACCESS_ODBC_DSN => 1,
 443       DBICTEST_MSACCESS_ODBC_USER => 0,
 444       DBICTEST_MSACCESS_ODBC_PASS => 0,
 445     ],
 446     req => {
 447       'Data::GUID' => '0',
 448     },
 449   },
 450
 451   test_rdbms_msaccess_ado => {
 452     include => 'rdbms_msaccess_ado',
 453     env => [
 454       DBICTEST_MSACCESS_ADO_DSN => 1,
 455       DBICTEST_MSACCESS_ADO_USER => 0,
 456       DBICTEST_MSACCESS_ADO_PASS => 0,
 457     ],
 458     req => {
 459       'Data::GUID' => 0,
 460     },
 461   },
 462
 463   test_rdbms_mysql => {
 464     include => 'rdbms_mysql',
 465     env => [
 466       DBICTEST_MYSQL_DSN => 1,
 467       DBICTEST_MYSQL_USER => 0,
 468       DBICTEST_MYSQL_PASS => 0,
 469     ],
 470   },
 471
 472   test_rdbms_oracle => {
 473     include => 'rdbms_oracle',
 474     env => [
 475       DBICTEST_ORA_DSN => 1,
 476       DBICTEST_ORA_USER => 0,
 477       DBICTEST_ORA_PASS => 0,
 478     ],
 479     req => {
 480       'DateTime::Format::Oracle' => '0',
 481       'DBD::Oracle'              => '1.24',
 482     },
 483   },
 484
 485   test_rdbms_ase => {
 486     include => 'rdbms_ase',
 487     env => [
 488       DBICTEST_SYBASE_DSN => 1,
 489       DBICTEST_SYBASE_USER => 0,
 490       DBICTEST_SYBASE_PASS => 0,
 491     ],
 492   },
 493
 494   test_rdbms_db2 => {
 495     include => 'rdbms_db2',
 496     env => [
 497       DBICTEST_DB2_DSN => 1,
 498       DBICTEST_DB2_USER => 0,
 499       DBICTEST_DB2_PASS => 0,
 500     ],
 501   },
 502
 503   test_rdbms_db2_400 => {
 504     include => 'rdbms_db2_400',
 505     env => [
 506       DBICTEST_DB2_400_DSN => 1,
 507       DBICTEST_DB2_400_USER => 0,
 508       DBICTEST_DB2_400_PASS => 0,
 509     ],
 510   },
 511
 512   test_rdbms_informix => {
 513     include => 'rdbms_informix',
 514     env => [
 515       DBICTEST_INFORMIX_DSN => 1,
 516       DBICTEST_INFORMIX_USER => 0,
 517       DBICTEST_INFORMIX_PASS => 0,
 518     ],
 519   },
 520
 521   test_rdbms_sqlanywhere => {
 522     include => 'rdbms_sqlanywhere',
 523     env => [
 524       DBICTEST_SQLANYWHERE_DSN => 1,
 525       DBICTEST_SQLANYWHERE_USER => 0,
 526       DBICTEST_SQLANYWHERE_PASS => 0,
 527     ],
 528   },
 529
 530   test_rdbms_sqlanywhere_odbc => {
 531     include => 'rdbms_sqlanywhere_odbc',
 532     env => [
 533       DBICTEST_SQLANYWHERE_ODBC_DSN => 1,
 534       DBICTEST_SQLANYWHERE_ODBC_USER => 0,
 535       DBICTEST_SQLANYWHERE_ODBC_PASS => 0,
 536     ],
 537   },
 538
 539   test_rdbms_firebird => {
 540     include => 'rdbms_firebird',
 541     env => [
 542       DBICTEST_FIREBIRD_DSN => 1,
 543       DBICTEST_FIREBIRD_USER => 0,
 544       DBICTEST_FIREBIRD_PASS => 0,
 545     ],
 546   },
 547
 548   test_rdbms_firebird_interbase => {
 549     include => 'rdbms_firebird_interbase',
 550     env => [
 551       DBICTEST_FIREBIRD_INTERBASE_DSN => 1,
 552       DBICTEST_FIREBIRD_INTERBASE_USER => 0,
 553       DBICTEST_FIREBIRD_INTERBASE_PASS => 0,
 554     ],
 555   },
 556
 557   test_rdbms_firebird_odbc => {
 558     include => 'rdbms_firebird_odbc',
 559     env => [
 560       DBICTEST_FIREBIRD_ODBC_DSN => 1,
 561       DBICTEST_FIREBIRD_ODBC_USER => 0,
 562       DBICTEST_FIREBIRD_ODBC_PASS => 0,
 563     ],
 564   },
 565
 566   test_memcached => {
 567     env => [
 568       DBICTEST_MEMCACHED => 1,
 569     ],
 570     req => {
 571       'Cache::Memcached' => 0,
 572     },
 573   },
 574
 575   dist_dir => {
 576     req => {
 577       %$test_and_dist_json_any,
 578       'ExtUtils::MakeMaker' => '6.64',
 579       'Pod::Inherit'        => '0.91',
 580     },
 581   },
 582
 583   dist_upload => {
 584     req => {
 585       'CPAN::Uploader' => '0.103001',
 586     },
 587   },
 588 };
 589
 590
 591
 592 ### Public API
 593
 594 sub import {
 595   my $class = shift;
 596
 597   if (@_) {
 598
 599     my $action = shift;
 600
 601     if ($action eq '-die_without') {
 602       my $err;
 603       {
 604         local $@;
 605         eval { $class->die_unless_req_ok_for(\@_); 1 }
 606           or $err = $@;
 607       }
 608       die "\n$err\n" if $err;
 609     }
 610     elsif ($action eq '-list_missing') {
 611       print $class->modreq_missing_for(\@_);
 612       print "\n";
 613       exit 0;
 614     }
 615     elsif ($action eq '-skip_all_without') {
 616
 617       # sanity check - make sure ->current_test is 0 and no plan has been declared
 618       do {
 619         local $@;
 620         defined eval {
 621           Test::Builder->new->current_test
 622             or
 623           Test::Builder->new->has_plan
 624         };
 625       } and croak("Unable to invoke -skip_all_without after testing has started");
 626
 627       if ( my $missing = $class->req_missing_for(\@_) ) {
 628
 629         die ("\nMandatory requirements not satisfied during release-testing: $missing\n\n")
 630           if $ENV{RELEASE_TESTING} and $class->_groups_to_reqs(\@_)->{release_testing_mandatory};
 631
 632         print "1..0 # SKIP requirements not satisfied: $missing\n";
 633         exit 0;
 634       }
 635     }
 636     elsif ($action =~ /^-/) {
 637       croak "Unknown import-time action '$action'";
 638     }
 639     else {
 640       croak "$class is not an exporter, unable to import '$action'";
 641     }
 642   }
 643
 644   1;
 645 }
 646
 647 sub unimport {
 648   croak( __PACKAGE__ . " does not implement unimport" );
 649 }
 650
 651 # OO for (mistakenly considered) ease of extensibility, not due to any need to
 652 # carry state of any sort. This API is currently used outside, so leave as-is.
 653 # FIXME - make sure to not propagate this further if module is extracted as a
 654 # standalone library - keep the stupidity to a DBIC-secific shim!
 655 #
 656 sub req_list_for {
 657   shift->_groups_to_reqs(shift)->{effective_modreqs};
 658 }
 659
 660 sub modreq_list_for {
 661   shift->_groups_to_reqs(shift)->{modreqs};
 662 }
 663
 664 sub req_group_list {
 665   +{ map
 666     { $_ => $_[0]->_groups_to_reqs($_) }
 667     keys %$dbic_reqs
 668   }
 669 }
 670
 671 sub req_errorlist_for { shift->modreq_errorlist_for(shift) }  # deprecated
 672 sub modreq_errorlist_for {
 673   my ($self, $groups) = @_;
 674   $self->_errorlist_for_modreqs( $self->_groups_to_reqs($groups)->{modreqs} );
 675 }
 676
 677 sub req_ok_for {
 678   shift->req_missing_for(shift) ? 0 : 1;
 679 }
 680
 681 sub req_missing_for {
 682   my ($self, $groups) = @_;
 683
 684   my $reqs = $self->_groups_to_reqs($groups);
 685   my $mods_missing = $self->modreq_missing_for($groups);
 686
 687   return '' if
 688     ! $mods_missing
 689       and
 690     ! $reqs->{missing_envvars}
 691   ;
 692
 693   my @res = $mods_missing || ();
 694
 695   push @res, 'the following group(s) of environment variables: ' . join ' and ', sort map
 696     { __envvar_group_desc($_) }
 697     @{$reqs->{missing_envvars}}
 698   if $reqs->{missing_envvars};
 699
 700   return (
 701     ( join ' as well as ', @res )
 702       .
 703     ( $reqs->{modreqs_fully_documented} ? " (see @{[ ref $self || $self ]} documentation for details)" : '' ),
 704   );
 705 }
 706
 707 sub modreq_missing_for {
 708   my ($self, $groups) = @_;
 709
 710   my $reqs = $self->_groups_to_reqs($groups);
 711   my $modreq_errors = $self->_errorlist_for_modreqs($reqs->{modreqs})
 712     or return '';
 713
 714   join ' ', map
 715     { $reqs->{modreqs}{$_} ? qq("$_~>=$reqs->{modreqs}{$_}") : $_ }
 716     sort { lc($a) cmp lc($b) } keys %$modreq_errors
 717   ;
 718 }
 719
 720 sub die_unless_req_ok_for {
 721   if (my $err = shift->req_missing_for(shift) ) {
 722     die "Unable to continue due to missing requirements: $err\n";
 723   }
 724 }
 725
 726
 727
 728 ### Private functions
 729
 730 # potentially shorten group desc
 731 sub __envvar_group_desc {
 732   my @envs = @{$_[0]};
 733
 734   my (@res, $last_prefix);
 735   while (my $ev = shift @envs) {
 736     my ($pref, $sep, $suff) = split / ([\_\-]) (?= [^\_\-]+ \z )/x, $ev;
 737
 738     if ( defined $sep and ($last_prefix||'') eq $pref ) {
 739         push @res, "...${sep}${suff}"
 740     }
 741     else {
 742       push @res, $ev;
 743     }
 744
 745     $last_prefix = $pref if $sep;
 746   }
 747
 748   join '/', @res;
 749 }
 750
 751
 752
 753 ### Private OO API
 754 our %req_unavailability_cache;
 755
 756 # this method is just a lister and envvar/metadata checker - it does not try to load anything
 757 my $processed_groups = {};
 758 sub _groups_to_reqs {
 759   my ($self, $groups) = @_;
 760
 761   $groups = [ $groups || () ]
 762     unless ref $groups eq 'ARRAY';
 763
 764   croak "@{[ (caller(1))[3] ]}() expects a requirement group name or arrayref of group names"
 765     unless @$groups;
 766
 767   my $ret = {
 768     modreqs => {},
 769     modreqs_fully_documented => 1,
 770   };
 771
 772   for my $group ( grep { ! $processed_groups->{$_} } @$groups ) {
 773
 774     $group =~ /\A [A-Za-z][0-9A-Z_a-z]* \z/x
 775       or croak "Invalid requirement group name '$group': only ascii alphanumerics and _ are allowed";
 776
 777     croak "Requirement group '$group' is not defined" unless defined $dbic_reqs->{$group};
 778
 779     my $group_reqs = $dbic_reqs->{$group}{req};
 780
 781     # sanity-check
 782     for (keys %$group_reqs) {
 783
 784       $_ =~ /\A [A-Z_a-z][0-9A-Z_a-z]* (?:::[0-9A-Z_a-z]+)* \z /x
 785         or croak "Requirement '$_' in group '$group' is not a valid module name";
 786
 787       # !!!DO NOT CHANGE!!!
 788       # remember - version.pm may not be available on the system
 789       croak "Requirement '$_' in group '$group' specifies an invalid version '$group_reqs->{$_}' (only plain non-underscored floating point decimals are supported)"
 790         if ( ($group_reqs->{$_}||0) !~ / \A [0-9]+ (?: \. [0-9]+ )? \z /x );
 791     }
 792
 793     # check if we have all required envvars if such names are defined
 794     my ($some_envs_required, $some_envs_missing);
 795     if (my @e = @{$dbic_reqs->{$group}{env} || [] }) {
 796
 797       croak "Unexpected 'env' attribute under group '$group' (only allowed in test_* groups)"
 798         unless $group =~ /^test_/;
 799
 800       croak "Unexpected *odd* list in 'env' under group '$group'"
 801         if @e % 2;
 802
 803       my @group_envnames_list;
 804
 805       # deconstruct the whole thing
 806       while (@e) {
 807         push @group_envnames_list, my $envname = shift @e;
 808
 809         # env required or not
 810         next unless shift @e;
 811
 812         $some_envs_required ||= 1;
 813
 814         $some_envs_missing ||= (
 815           ! defined $ENV{$envname}
 816             or
 817           ! length $ENV{$envname}
 818         );
 819       }
 820
 821       croak "None of the envvars in group '$group' declared as required, making the requirement moot"
 822         unless $some_envs_required;
 823
 824       push @{$ret->{missing_envvars}}, \@group_envnames_list if $some_envs_missing;
 825     }
 826
 827     # get the reqs for includes if any
 828     my $inc_reqs;
 829     if (my $incs = $dbic_reqs->{$group}{include}) {
 830       $incs = [ $incs ] unless ref $incs eq 'ARRAY';
 831
 832       croak "Malformed 'include' for group '$group': must be another existing group name or arrayref of existing group names"
 833         unless @$incs;
 834
 835       local $processed_groups->{$group} = 1;
 836
 837       my $subreqs = $self->_groups_to_reqs($incs);
 838
 839       croak "Includes with variable effective_modreqs not yet supported"
 840         if $subreqs->{effective_modreqs_differ};
 841
 842       $inc_reqs = $subreqs->{modreqs};
 843
 844     }
 845
 846     # assemble into the final ret
 847     for my $type (
 848       'modreqs',
 849       $some_envs_missing ? () : 'effective_modreqs'
 850     ) {
 851       for my $req_bag ($group_reqs, $inc_reqs||()) {
 852         for my $mod (keys %$req_bag) {
 853
 854           $ret->{$type}{$mod} = $req_bag->{$mod}||0 if (
 855
 856             ! exists $ret->{$type}{$mod}
 857               or
 858             # we sanitized the version to be numeric above - we can just -gt it
 859             ($req_bag->{$mod}||0) > $ret->{$type}{$mod}
 860
 861           );
 862         }
 863       }
 864     }
 865
 866     $ret->{effective_modreqs_differ} ||= !!$some_envs_missing;
 867
 868     $ret->{modreqs_fully_documented} &&= !!$dbic_reqs->{$group}{pod};
 869
 870     $ret->{release_testing_mandatory} ||= !!$dbic_reqs->{$group}{release_testing_mandatory};
 871   }
 872
 873   return $ret;
 874 }
 875
 876
 877 # this method tries to load specified modreqs and returns a hashref of
 878 # module/loaderror pairs for anything that failed
 879 sub _errorlist_for_modreqs {
 880   # args supposedly already went through _groups_to_reqs and are therefore sanitized
 881   # safe to eval at will
 882   my ($self, $reqs) = @_;
 883
 884   my $ret;
 885
 886   for my $m ( keys %$reqs ) {
 887     my $v = $reqs->{$m};
 888
 889     if (! exists $req_unavailability_cache{$m}{$v} ) {
 890       local $@;
 891       eval( "require $m;" . ( $v ? "$m->VERSION(q($v))" : '' ) );
 892       $req_unavailability_cache{$m}{$v} = $@;
 893     }
 894
 895     $ret->{$m} = $req_unavailability_cache{$m}{$v}
 896       if $req_unavailability_cache{$m}{$v};
 897   }
 898
 899   $ret;
 900 }
 901
 902
 903 # This is to be called by the author only (automatically in Makefile.PL)
 904 sub _gen_pod {
 905   my ($class, $distver, $pod_dir) = @_;
 906
 907   die "No POD root dir supplied" unless $pod_dir;
 908
 909   $distver ||=
 910     eval { require DBIx::Class; DBIx::Class->VERSION; }
 911       ||
 912     die
 913 "\n\n---------------------------------------------------------------------\n" .
 914 'Unable to load core DBIx::Class module to determine current version, '.
 915 'possibly due to missing dependencies. Author-mode autodocumentation ' .
 916 "halted\n\n" . $@ .
 917 "\n\n---------------------------------------------------------------------\n"
 918   ;
 919
 920   # do not ask for a recent version, use 1.x API calls
 921   # this *may* execute on a smoker with old perl or whatnot
 922   require File::Path;
 923
 924   (my $modfn = __PACKAGE__ . '.pm') =~ s|::|/|g;
 925
 926   (my $podfn = "$pod_dir/$modfn") =~ s/\.pm$/\.pod/;
 927   (my $dir = $podfn) =~ s|/[^/]+$||;
 928
 929   File::Path::mkpath([$dir]);
 930
 931   my $sqltver = $class->req_list_for('deploy')->{'SQL::Translator'}
 932     or die "Hrmm? No sqlt dep?";
 933
 934
 935   my @chunks;
 936
 937 #@@
 938 #@@ HEADER
 939 #@@
 940   push @chunks, <<"EOC";
 941 #########################################################################
 942 #####################  A U T O G E N E R A T E D ########################
 943 #########################################################################
 944 #
 945 # The contents of this POD file are auto-generated.  Any changes you make
 946 # will be lost. If you need to change the generated text edit _gen_pod()
 947 # at the end of $modfn
 948 #
 949
 950 =head1 NAME
 951
 952 $class - Optional module dependency specifications (for module authors)
 953 EOC
 954
 955
 956 #@@
 957 #@@ SYNOPSIS HEADING
 958 #@@
 959   push @chunks, <<"EOC";
 960 =head1 SYNOPSIS
 961
 962 Somewhere in your build-file (e.g. L<ExtUtils::MakeMaker>'s F<Makefile.PL>):
 963
 964   ...
 965
 966   \$EUMM_ARGS{CONFIGURE_REQUIRES} = {
 967     \%{ \$EUMM_ARGS{CONFIGURE_REQUIRES} || {} },
 968     'DBIx::Class' => '$distver',
 969   };
 970
 971   ...
 972
 973   my %DBIC_DEPLOY_DEPS = %{ eval {
 974     require $class;
 975     $class->req_list_for('deploy');
 976   } || {} };
 977
 978   \$EUMM_ARGS{PREREQ_PM} = {
 979     \%DBIC_DEPLOY_DEPS,
 980     \%{ \$EUMM_ARGS{PREREQ_PM} || {} },
 981   };
 982
 983   ...
 984
 985   ExtUtils::MakeMaker::WriteMakefile(\%EUMM_ARGS);
 986
 987 B<Note>: The C<eval> protection within the example is due to support for
 988 requirements during L<the C<configure> build phase|CPAN::Meta::Spec/Phases>
 989 not being available on a sufficient portion of production installations of
 990 Perl. Robust support for such dependency requirements is available in the
 991 L<CPAN> installer only since version C<1.94_56> first made available for
 992 production with perl version C<5.12>. It is the belief of the current
 993 maintainer that support for requirements during the C<configure> build phase
 994 will not be sufficiently ubiquitous until the B<year 2020> at the earliest,
 995 hence the extra care demonstrated above. It should also be noted that some
 996 3rd party installers (e.g. L<cpanminus|App::cpanminus>) do the right thing
 997 with configure requirements independent from the versions of perl and CPAN
 998 available.
 999 EOC
1000
1001
1002 #@@
1003 #@@ DESCRIPTION HEADING
1004 #@@
1005   push @chunks, <<'EOC';
1006 =head1 DESCRIPTION
1007
1008 Some of the less-frequently used features of L<DBIx::Class> have external
1009 module dependencies on their own. In order not to burden the average user
1010 with modules they will never use, these optional dependencies are not included
1011 in the base Makefile.PL. Instead an exception with a descriptive message is
1012 thrown when a specific feature can't find one or several modules required for
1013 its operation. This module is the central holding place for the current list
1014 of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
1015 authors alike.
1016
1017 Dependencies are organized in L<groups|/CURRENT REQUIREMENT GROUPS> where each
1018 group can list one or more required modules, with an optional minimum version
1019 (or 0 for any version). In addition groups prefixed with C<test_> can specify
1020 a set of environment variables, some (or all) of which are marked as required
1021 for the group to be considered by L</req_list_for>
1022
1023 Each group name (or a combination thereof) can be used in the
1024 L<public methods|/METHODS> as described below.
1025 EOC
1026
1027
1028 #@@
1029 #@@ REQUIREMENT GROUPLIST HEADING
1030 #@@
1031   push @chunks, '=head1 CURRENT REQUIREMENT GROUPS';
1032
1033   for my $group (sort keys %$dbic_reqs) {
1034     my $p = $dbic_reqs->{$group}{pod}
1035       or next;
1036
1037     my $modlist = $class->modreq_list_for($group);
1038
1039     next unless keys %$modlist;
1040
1041     push @chunks, (
1042       "=head2 $p->{title}",
1043       "$p->{desc}",
1044       '=over',
1045       ( map { "=item * $_" . ($modlist->{$_} ? " >= $modlist->{$_}" : '') } (sort keys %$modlist) ),
1046       '=back',
1047       "Requirement group: B<$group>",
1048     );
1049   }
1050
1051
1052 #@@
1053 #@@ API DOCUMENTATION HEADING
1054 #@@
1055   push @chunks, <<'EOC';
1056
1057 =head1 IMPORT-LIKE ACTIONS
1058
1059 Even though this module is not an L<Exporter>, it recognizes several C<actions>
1060 supplied to its C<import> method.
1061
1062 =head2 -skip_all_without
1063
1064 =over
1065
1066 =item Arguments: @group_names
1067
1068 =back
1069
1070 A convenience wrapper for use during testing:
1071 EOC
1072
1073   push @chunks, " use $class -skip_all_without => qw(admin test_rdbms_mysql);";
1074
1075   push @chunks, 'Roughly equivalent to the following code:';
1076
1077   push @chunks, sprintf <<'EOS', ($class) x 2;
1078
1079  BEGIN {
1080    require %s;
1081    if ( my $missing = %s->req_missing_for(\@group_names_) ) {
1082      print "1..0 # SKIP requirements not satisfied: $missing\n";
1083      exit 0;
1084    }
1085  }
1086 EOS
1087
1088   push @chunks, <<'EOC';
1089
1090 It also takes into account the C<RELEASE_TESTING> environment variable and
1091 behaves like L</-die_without> for any requirement groups marked as
1092 C<release_testing_mandatory>.
1093
1094 =head2 -die_without
1095
1096 =over
1097
1098 =item Arguments: @group_names
1099
1100 =back
1101
1102 A convenience wrapper around L</die_unless_req_ok_for>:
1103 EOC
1104
1105   push @chunks, " use $class -die_without => qw(deploy admin);";
1106
1107   push @chunks, <<'EOC';
1108
1109 =head2 -list_missing
1110
1111 =over
1112
1113 =item Arguments: @group_names
1114
1115 =back
1116
1117 A convenience wrapper around L</modreq_missing_for>:
1118
1119  perl -Ilib -MDBIx::Class::Optional::Dependencies=-list_missing,deploy,admin | cpanm
1120
1121 =head1 METHODS
1122
1123 =head2 req_group_list
1124
1125 =over
1126
1127 =item Arguments: none
1128
1129 =item Return Value: \%list_of_requirement_groups
1130
1131 =back
1132
1133 This method should be used by DBIx::Class packagers, to get a hashref of all
1134 dependencies B<keyed> by dependency group. Each key (group name), or a combination
1135 thereof (as an arrayref) can be supplied to the methods below.
1136 The B<values> of the returned hash are currently a set of options B<without a
1137 well defined structure>. If you have use for any of the contents - contact the
1138 maintainers, instead of treating this as public (left alone stable) API.
1139
1140 =head2 req_list_for
1141
1142 =over
1143
1144 =item Arguments: $group_name | \@group_names
1145
1146 =item Return Value: \%set_of_module_version_pairs
1147
1148 =back
1149
1150 This method should be used by DBIx::Class extension authors, to determine the
1151 version of modules a specific set of features requires for this version of
1152 DBIx::Class (regardless of their availability on the system).
1153 See the L</SYNOPSIS> for a real-world example.
1154
1155 When handling C<test_*> groups this method behaves B<differently> from
1156 L</modreq_list_for> below (and is the only such inconsistency among the
1157 C<req_*> methods). If a particular group declares as requirements some
1158 C<environment variables> and these requirements are not satisfied (the envvars
1159 are unset) - then the C<module requirements> of this group are not included in
1160 the returned list.
1161
1162 =head2 modreq_list_for
1163
1164 =over
1165
1166 =item Arguments: $group_name | \@group_names
1167
1168 =item Return Value: \%set_of_module_version_pairs
1169
1170 =back
1171
1172 Same as L</req_list_for> but does not take into consideration any
1173 C<environment variable requirements> - returns just the list of required
1174 modules.
1175
1176 =head2 req_ok_for
1177
1178 =over
1179
1180 =item Arguments: $group_name | \@group_names
1181
1182 =item Return Value: 1|0
1183
1184 =back
1185
1186 Returns true or false depending on whether all modules/envvars required by
1187 the group(s) are loadable/set on the system.
1188
1189 =head2 req_missing_for
1190
1191 =over
1192
1193 =item Arguments: $group_name | \@group_names
1194
1195 =item Return Value: $error_message_string
1196
1197 =back
1198
1199 Returns a single-line string suitable for inclusion in larger error messages.
1200 This method would normally be used by DBIx::Class core features, to indicate to
1201 the user that they need to install specific modules and/or set specific
1202 environment variables before being able to use a specific feature set.
1203
1204 For example if some of the requirements for C<deploy> are not available,
1205 the returned string could look like:
1206 EOC
1207
1208   push @chunks, qq{ "SQL::Translator~>=$sqltver" (see $class documentation for details)};
1209
1210   push @chunks, <<'EOC';
1211 The author is expected to prepend the necessary text to this message before
1212 returning the actual error seen by the user. See also L</modreq_missing_for>
1213
1214 =head2 modreq_missing_for
1215
1216 =over
1217
1218 =item Arguments: $group_name | \@group_names
1219
1220 =item Return Value: $error_message_string
1221
1222 =back
1223
1224 Same as L</req_missing_for> except that the error string is guaranteed to be
1225 either empty, or contain a set of module requirement specifications suitable
1226 for piping to e.g. L<cpanminus|App::cpanminus>. The method explicitly does not
1227 attempt to validate the state of required environment variables (if any).
1228
1229 For instance if some of the requirements for C<deploy> are not available,
1230 the returned string could look like:
1231 EOC
1232
1233   push @chunks, qq{ "SQL::Translator~>=$sqltver"};
1234
1235   push @chunks, <<'EOC';
1236
1237 See also L</-list_missing>.
1238
1239 =head2 die_unless_req_ok_for
1240
1241 =over
1242
1243 =item Arguments: $group_name | \@group_names
1244
1245 =back
1246
1247 Checks if L</req_ok_for> passes for the supplied group(s), and
1248 in case of failure throws an exception including the information
1249 from L</req_missing_for>. See also L</-die_without>.
1250
1251 =head2 modreq_errorlist_for
1252
1253 =over
1254
1255 =item Arguments: $group_name | \@group_names
1256
1257 =item Return Value: \%set_of_loaderrors_per_module
1258
1259 =back
1260
1261 Returns a hashref containing the actual errors that occurred while attempting
1262 to load each module in the requirement group(s).
1263
1264 =head2 req_errorlist_for
1265
1266 Deprecated method name, equivalent (via proxy) to L</modreq_errorlist_for>.
1267
1268 EOC
1269
1270 #@@
1271 #@@ FOOTER
1272 #@@
1273   push @chunks, <<'EOC';
1274 =head1 FURTHER QUESTIONS?
1275
1276 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
1277
1278 =head1 COPYRIGHT AND LICENSE
1279
1280 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
1281 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
1282 redistribute it and/or modify it under the same terms as the
1283 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
1284 EOC
1285
1286   eval {
1287     open (my $fh, '>', $podfn) or die;
1288     print $fh join ("\n\n", @chunks) or die;
1289     print $fh "\n" or die;
1290     close ($fh) or die;
1291   } or croak( "Unable to write $podfn: " . ( $! || $@ || 'unknown error') );
1292 }
1293
1294 1;