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 BEGIN {
   6   if ( $ENV{RELEASE_TESTING} ) {
   7     require warnings and warnings->import;
   8     require strict and strict->import;
   9   }
  10 }
  11
  12 sub croak {
  13   require Carp;
  14   Carp::croak(@_);
  15 };
  16 ###
  17
  18 # NO EXTERNAL NON-5.8.1 CORE DEPENDENCIES EVER (e.g. C::A::G)
  19 # This module is to be loaded by Makefile.PM on a pristine system
  20
  21 # POD is generated automatically by calling _gen_pod from the
  22 # Makefile.PL in $AUTHOR mode
  23
  24 # *DELIBERATELY* not making a group for these - they must disappear
  25 # forever as optdeps in the first place
  26 my $moose_basic = {
  27   'Moose'                         => '0.98',
  28   'MooseX::Types'                 => '0.21',
  29   'MooseX::Types::LoadableClass'  => '0.011',
  30 };
  31
  32 my $dbic_reqs = {
  33
  34   # NOTE: the rationale for 2 JSON::Any versions is that
  35   # we need the newer only to work around JSON::XS, which
  36   # itself is an optional dep
  37   _json_any => {
  38     req => {
  39       'JSON::Any' => '1.23',
  40     },
  41   },
  42
  43   _json_xs_compatible_json_any => {
  44     req => {
  45       'JSON::Any' => '1.31',
  46     },
  47   },
  48
  49   # a common placeholder for engines with IC::DT support based off DT::F::S
  50   _icdt_strptime_based => {
  51     augment => {
  52       icdt => {
  53         req => {
  54           'DateTime::Format::Strptime' => '1.2',
  55         },
  56       },
  57     }
  58   },
  59
  60   _rdbms_generic_odbc => {
  61     req => {
  62       'DBD::ODBC' => 0,
  63     }
  64   },
  65
  66   _rdbms_generic_ado => {
  67     req => {
  68       'DBD::ADO' => 0,
  69     }
  70   },
  71
  72   # must list any dep used by adhoc testing
  73   # this prevents the "skips due to forgotten deps" issue
  74   test_adhoc => {
  75     req => {
  76       'Class::DBI::Plugin::DeepAbstractSearch' => '0',
  77       'Class::DBI' => '3.000005',
  78       'Date::Simple' => '3.03',
  79       'YAML' => '0',
  80       'Class::Unload' => '0.07',
  81       'Time::Piece' => '0',
  82       'Time::Piece::MySQL' => '0',
  83     },
  84   },
  85
  86   replicated => {
  87     req => $moose_basic,
  88     pod => {
  89       title => 'Storage::Replicated',
  90       desc => 'Modules required for L<DBIx::Class::Storage::DBI::Replicated>',
  91     },
  92   },
  93
  94   test_replicated => {
  95     include => 'replicated',
  96     req => {
  97       'Test::Moose' => '0',
  98     },
  99   },
 100
 101   admin => {
 102     include => '_json_any',
 103     req => {
 104       %$moose_basic,
 105       'MooseX::Types::Path::Class' => '0.05',
 106       'MooseX::Types::JSON' => '0.02',
 107     },
 108     pod => {
 109       title => 'DBIx::Class::Admin',
 110       desc => 'Modules required for the DBIx::Class administrative library',
 111     },
 112   },
 113
 114   admin_script => {
 115     include => 'admin',
 116     req => {
 117       'Getopt::Long::Descriptive' => '0.081',
 118       'Text::CSV' => '1.16',
 119     },
 120     pod => {
 121       title => 'dbicadmin',
 122       desc => 'Modules required for the CLI DBIx::Class interface dbicadmin',
 123     },
 124   },
 125
 126   deploy => {
 127     req => {
 128       'SQL::Translator'           => '0.11018',
 129     },
 130     pod => {
 131       title => 'Storage::DBI::deploy()',
 132       desc => 'Modules required for L<DBIx::Class::Storage::DBI/deployment_statements> and L<DBIx::Class::Schema/deploy>',
 133     },
 134   },
 135
 136   icdt => {
 137     req => {
 138       'DateTime' => '0.55',
 139       'DateTime::TimeZone::OlsonDB' => 0,
 140     },
 141     pod => {
 142       title => 'InflateColumn::DateTime support',
 143       desc =>
 144         'Modules required for L<DBIx::Class::InflateColumn::DateTime>. '
 145       . 'Note that this group does not require much on its own, but '
 146       . 'instead is augmented by various RDBMS-specific groups. See the '
 147       . 'documentation of each C<rbms_*> group for details',
 148     },
 149   },
 150
 151   id_shortener => {
 152     req => {
 153       'Math::BigInt' => '1.80',
 154       'Math::Base36' => '0.07',
 155     },
 156   },
 157
 158   cdbicompat => {
 159     req => {
 160       'Class::Data::Inheritable' => '0',
 161       'Class::Trigger' => '0',
 162       'DBIx::ContextualFetch' => '0',
 163       'Clone' => '0.32',
 164     },
 165     pod => {
 166       title => 'DBIx::Class::CDBICompat support',
 167       desc => 'Modules required for L<DBIx::Class::CDBICompat>'
 168     },
 169   },
 170
 171   test_pod => {
 172     req => {
 173       'Test::Pod'                 => '1.42',
 174     },
 175     release_testing_mandatory => 1,
 176   },
 177
 178   test_podcoverage => {
 179     req => {
 180       'Test::Pod::Coverage'       => '1.08',
 181       'Pod::Coverage'             => '0.20',
 182     },
 183     release_testing_mandatory => 1,
 184   },
 185
 186   test_whitespace => {
 187     req => {
 188       'Test::EOL'                 => '1.0',
 189       'Test::NoTabs'              => '0.9',
 190     },
 191     release_testing_mandatory => 1,
 192   },
 193
 194   test_strictures => {
 195     req => {
 196       'Test::Strict'              => '0.20',
 197     },
 198     release_testing_mandatory => 1,
 199   },
 200
 201   test_prettydebug => {
 202     include => '_json_any',
 203   },
 204
 205   test_admin_script => {
 206     include => [qw( admin_script _json_xs_compatible_json_any )],
 207     req => {
 208       'JSON' => 0,
 209       'JSON::PP' => 0,
 210       'Cpanel::JSON::XS' => 0,
 211       'JSON::XS' => 0,
 212       $^O eq 'MSWin32'
 213         # for t/admin/10script.t
 214         ? ('Win32::ShellQuote' => 0)
 215         # DWIW does not compile (./configure even) on win32
 216         : ('JSON::DWIW' => 0 )
 217       ,
 218     }
 219   },
 220
 221   test_leaks_heavy => {
 222     req => {
 223       'Class::MethodCache' => '0.02',
 224       'PadWalker' => '1.06',
 225     },
 226   },
 227
 228
 229   # this is just for completeness as SQLite
 230   # is a core dep of DBIC for testing
 231   rdbms_sqlite => {
 232     req => {
 233       'DBD::SQLite' => 0,
 234     },
 235     pod => {
 236       title => 'SQLite support',
 237       desc => 'Modules required to connect to SQLite',
 238     },
 239     augment => {
 240       icdt => {
 241         req => {
 242           'DateTime::Format::SQLite' => '0',
 243         },
 244       },
 245     },
 246   },
 247
 248   # centralize the specification, as we have ICDT tests which can
 249   # test the full behavior of RDBMS-specific ICDT on top of bare SQLite
 250   # not _-prefixed so that it will show up under req_group_list
 251   icdt_pg => {
 252     augment => {
 253       icdt => {
 254         req => {
 255           'DateTime::Format::Pg' => '0.16004',
 256         },
 257       },
 258     },
 259   },
 260
 261   rdbms_pg => {
 262     include => 'icdt_pg',
 263     req => {
 264       # when changing this list make sure to adjust xt/optional_deps.t
 265       'DBD::Pg' => 0,
 266     },
 267     pod => {
 268       title => 'PostgreSQL support',
 269       desc => 'Modules required to connect to PostgreSQL',
 270     },
 271   },
 272
 273   _rdbms_mssql_common => {
 274     include => '_icdt_strptime_based',
 275   },
 276
 277   rdbms_mssql_odbc => {
 278     include => [qw( _rdbms_generic_odbc _rdbms_mssql_common )],
 279     pod => {
 280       title => 'MSSQL support via DBD::ODBC',
 281       desc => 'Modules required to connect to MSSQL via DBD::ODBC',
 282     },
 283   },
 284
 285   rdbms_mssql_sybase => {
 286     include => '_rdbms_mssql_common',
 287     req => {
 288       'DBD::Sybase' => 0,
 289     },
 290     pod => {
 291       title => 'MSSQL support via DBD::Sybase',
 292       desc => 'Modules required to connect to MSSQL via DBD::Sybase',
 293     },
 294   },
 295
 296   rdbms_mssql_ado => {
 297     include => [qw( _rdbms_generic_ado _rdbms_mssql_common )],
 298     pod => {
 299       title => 'MSSQL support via DBD::ADO (Windows only)',
 300       desc => 'Modules required to connect to MSSQL via DBD::ADO. This particular DBD is available on Windows only',
 301     },
 302   },
 303
 304   _rdbms_msaccess_common => {
 305     include => '_icdt_strptime_based',
 306   },
 307
 308   rdbms_msaccess_odbc => {
 309     include => [qw( _rdbms_generic_odbc _rdbms_msaccess_common )],
 310     pod => {
 311       title => 'MS Access support via DBD::ODBC',
 312       desc => 'Modules required to connect to MS Access via DBD::ODBC',
 313     },
 314   },
 315
 316   rdbms_msaccess_ado => {
 317     include => [qw( _rdbms_generic_ado _rdbms_msaccess_common )],
 318     pod => {
 319       title => 'MS Access support via DBD::ADO (Windows only)',
 320       desc => 'Modules required to connect to MS Access via DBD::ADO. This particular DBD is available on Windows only',
 321     },
 322   },
 323
 324   # centralize the specification, as we have ICDT tests which can
 325   # test the full behavior of RDBMS-specific ICDT on top of bare SQLite
 326   # not _-prefixed so that it will show up under req_group_list
 327   icdt_mysql => {
 328     augment => {
 329       icdt => {
 330         req => {
 331           'DateTime::Format::MySQL' => '0',
 332         },
 333       },
 334     },
 335   },
 336
 337   rdbms_mysql => {
 338     include => 'icdt_mysql',
 339     req => {
 340       'DBD::mysql' => 0,
 341     },
 342     pod => {
 343       title => 'MySQL support',
 344       desc => 'Modules required to connect to MySQL',
 345     },
 346   },
 347
 348   rdbms_oracle => {
 349     include => 'id_shortener',
 350     req => {
 351       'DBD::Oracle' => 0,
 352     },
 353     pod => {
 354       title => 'Oracle support',
 355       desc => 'Modules required to connect to Oracle',
 356     },
 357     augment => {
 358       icdt => {
 359         req => {
 360           'DateTime::Format::Oracle' => '0',
 361         },
 362       },
 363     },
 364   },
 365
 366   rdbms_ase => {
 367     include => '_icdt_strptime_based',
 368     req => {
 369       'DBD::Sybase' => 0,
 370     },
 371     pod => {
 372       title => 'Sybase ASE support',
 373       desc => 'Modules required to connect to Sybase ASE',
 374     },
 375   },
 376
 377   _rdbms_db2_common => {
 378     augment => {
 379       icdt => {
 380         req => {
 381           'DateTime::Format::DB2' => '0',
 382         },
 383       },
 384     },
 385   },
 386
 387   rdbms_db2 => {
 388     include => '_rdbms_db2_common',
 389     req => {
 390       'DBD::DB2' => 0,
 391     },
 392     pod => {
 393       title => 'DB2 support',
 394       desc => 'Modules required to connect to DB2',
 395     },
 396   },
 397
 398   rdbms_db2_400 => {
 399     include => [qw( _rdbms_generic_odbc _rdbms_db2_common )],
 400     pod => {
 401       title => 'DB2 on AS/400 support',
 402       desc => 'Modules required to connect to DB2 on AS/400',
 403     },
 404   },
 405
 406   rdbms_informix => {
 407     include => '_icdt_strptime_based',
 408     req => {
 409       'DBD::Informix' => 0,
 410     },
 411     pod => {
 412       title => 'Informix support',
 413       desc => 'Modules required to connect to Informix',
 414     },
 415   },
 416
 417   _rdbms_sqlanywhere_common => {
 418     inclide => '_icdt_strptime_based',
 419   },
 420
 421   rdbms_sqlanywhere => {
 422     include => '_rdbms_sqlanywhere_common',
 423     req => {
 424       'DBD::SQLAnywhere' => 0,
 425     },
 426     pod => {
 427       title => 'SQLAnywhere support',
 428       desc => 'Modules required to connect to SQLAnywhere',
 429     },
 430   },
 431
 432   rdbms_sqlanywhere_odbc => {
 433     include => [qw( _rdbms_generic_odbc _rdbms_sqlanywhere_common )],
 434     pod => {
 435       title => 'SQLAnywhere support via DBD::ODBC',
 436       desc => 'Modules required to connect to SQLAnywhere via DBD::ODBC',
 437     },
 438   },
 439
 440   _rdbms_firebird_common => {
 441     include => '_icdt_strptime_based',
 442   },
 443
 444   rdbms_firebird => {
 445     include => '_rdbms_firebird_common',
 446     req => {
 447       'DBD::Firebird' => 0,
 448     },
 449     pod => {
 450       title => 'Firebird support',
 451       desc => 'Modules required to connect to Firebird',
 452     },
 453   },
 454
 455   rdbms_firebird_interbase => {
 456     include => '_rdbms_firebird_common',
 457     req => {
 458       'DBD::InterBase' => 0,
 459     },
 460     pod => {
 461       title => 'Firebird support via DBD::InterBase',
 462       desc => 'Modules required to connect to Firebird via DBD::InterBase',
 463     },
 464   },
 465
 466   rdbms_firebird_odbc => {
 467     include => [qw( _rdbms_generic_odbc _rdbms_firebird_common )],
 468     pod => {
 469       title => 'Firebird support via DBD::ODBC',
 470       desc => 'Modules required to connect to Firebird via DBD::ODBC',
 471     },
 472   },
 473
 474   test_rdbms_sqlite => {
 475     include => 'rdbms_sqlite',
 476     req => {
 477       ###
 478       ### IMPORTANT - do not raise this dependency
 479       ### even though many bugfixes are present in newer versions, the general DBIC
 480       ### rule is to bend over backwards for available DBDs (given upgrading them is
 481       ### often *not* easy or even possible)
 482       ###
 483       'DBD::SQLite' => '1.29',
 484     },
 485   },
 486
 487   test_rdbms_pg => {
 488     include => 'rdbms_pg',
 489     env => [
 490       DBICTEST_PG_DSN => 1,
 491       DBICTEST_PG_USER => 0,
 492       DBICTEST_PG_PASS => 0,
 493     ],
 494     req => {
 495       # the order does matter because the rdbms support group might require
 496       # a different version that the test group
 497       #
 498       # when changing this list make sure to adjust xt/optional_deps.t
 499       'DBD::Pg' => '2.009002',  # specific version to test bytea
 500     },
 501   },
 502
 503   test_rdbms_mssql_odbc => {
 504     include => 'rdbms_mssql_odbc',
 505     env => [
 506       DBICTEST_MSSQL_ODBC_DSN => 1,
 507       DBICTEST_MSSQL_ODBC_USER => 0,
 508       DBICTEST_MSSQL_ODBC_PASS => 0,
 509     ],
 510   },
 511
 512   test_rdbms_mssql_ado => {
 513     include => 'rdbms_mssql_ado',
 514     env => [
 515       DBICTEST_MSSQL_ADO_DSN => 1,
 516       DBICTEST_MSSQL_ADO_USER => 0,
 517       DBICTEST_MSSQL_ADO_PASS => 0,
 518     ],
 519   },
 520
 521   test_rdbms_mssql_sybase => {
 522     include => 'rdbms_mssql_sybase',
 523     env => [
 524       DBICTEST_MSSQL_DSN => 1,
 525       DBICTEST_MSSQL_USER => 0,
 526       DBICTEST_MSSQL_PASS => 0,
 527     ],
 528   },
 529
 530   test_rdbms_msaccess_odbc => {
 531     include => 'rdbms_msaccess_odbc',
 532     env => [
 533       DBICTEST_MSACCESS_ODBC_DSN => 1,
 534       DBICTEST_MSACCESS_ODBC_USER => 0,
 535       DBICTEST_MSACCESS_ODBC_PASS => 0,
 536     ],
 537     req => {
 538       'Data::GUID' => '0',
 539     },
 540   },
 541
 542   test_rdbms_msaccess_ado => {
 543     include => 'rdbms_msaccess_ado',
 544     env => [
 545       DBICTEST_MSACCESS_ADO_DSN => 1,
 546       DBICTEST_MSACCESS_ADO_USER => 0,
 547       DBICTEST_MSACCESS_ADO_PASS => 0,
 548     ],
 549     req => {
 550       'Data::GUID' => 0,
 551     },
 552   },
 553
 554   test_rdbms_mysql => {
 555     include => 'rdbms_mysql',
 556     env => [
 557       DBICTEST_MYSQL_DSN => 1,
 558       DBICTEST_MYSQL_USER => 0,
 559       DBICTEST_MYSQL_PASS => 0,
 560     ],
 561   },
 562
 563   test_rdbms_oracle => {
 564     include => 'rdbms_oracle',
 565     env => [
 566       DBICTEST_ORA_DSN => 1,
 567       DBICTEST_ORA_USER => 0,
 568       DBICTEST_ORA_PASS => 0,
 569     ],
 570     req => {
 571       'DBD::Oracle'              => '1.24',
 572     },
 573   },
 574
 575   test_rdbms_ase => {
 576     include => 'rdbms_ase',
 577     env => [
 578       DBICTEST_SYBASE_DSN => 1,
 579       DBICTEST_SYBASE_USER => 0,
 580       DBICTEST_SYBASE_PASS => 0,
 581     ],
 582   },
 583
 584   test_rdbms_db2 => {
 585     include => 'rdbms_db2',
 586     env => [
 587       DBICTEST_DB2_DSN => 1,
 588       DBICTEST_DB2_USER => 0,
 589       DBICTEST_DB2_PASS => 0,
 590     ],
 591   },
 592
 593   test_rdbms_db2_400 => {
 594     include => 'rdbms_db2_400',
 595     env => [
 596       DBICTEST_DB2_400_DSN => 1,
 597       DBICTEST_DB2_400_USER => 0,
 598       DBICTEST_DB2_400_PASS => 0,
 599     ],
 600   },
 601
 602   test_rdbms_informix => {
 603     include => 'rdbms_informix',
 604     env => [
 605       DBICTEST_INFORMIX_DSN => 1,
 606       DBICTEST_INFORMIX_USER => 0,
 607       DBICTEST_INFORMIX_PASS => 0,
 608     ],
 609   },
 610
 611   test_rdbms_sqlanywhere => {
 612     include => 'rdbms_sqlanywhere',
 613     env => [
 614       DBICTEST_SQLANYWHERE_DSN => 1,
 615       DBICTEST_SQLANYWHERE_USER => 0,
 616       DBICTEST_SQLANYWHERE_PASS => 0,
 617     ],
 618   },
 619
 620   test_rdbms_sqlanywhere_odbc => {
 621     include => 'rdbms_sqlanywhere_odbc',
 622     env => [
 623       DBICTEST_SQLANYWHERE_ODBC_DSN => 1,
 624       DBICTEST_SQLANYWHERE_ODBC_USER => 0,
 625       DBICTEST_SQLANYWHERE_ODBC_PASS => 0,
 626     ],
 627   },
 628
 629   test_rdbms_firebird => {
 630     include => 'rdbms_firebird',
 631     env => [
 632       DBICTEST_FIREBIRD_DSN => 1,
 633       DBICTEST_FIREBIRD_USER => 0,
 634       DBICTEST_FIREBIRD_PASS => 0,
 635     ],
 636   },
 637
 638   test_rdbms_firebird_interbase => {
 639     include => 'rdbms_firebird_interbase',
 640     env => [
 641       DBICTEST_FIREBIRD_INTERBASE_DSN => 1,
 642       DBICTEST_FIREBIRD_INTERBASE_USER => 0,
 643       DBICTEST_FIREBIRD_INTERBASE_PASS => 0,
 644     ],
 645   },
 646
 647   test_rdbms_firebird_odbc => {
 648     include => 'rdbms_firebird_odbc',
 649     env => [
 650       DBICTEST_FIREBIRD_ODBC_DSN => 1,
 651       DBICTEST_FIREBIRD_ODBC_USER => 0,
 652       DBICTEST_FIREBIRD_ODBC_PASS => 0,
 653     ],
 654   },
 655
 656   test_memcached => {
 657     env => [
 658       DBICTEST_MEMCACHED => 1,
 659     ],
 660     req => {
 661       'Cache::Memcached' => 0,
 662     },
 663   },
 664
 665   dist_dir => {
 666     # we need to run the dbicadmin so we can self-generate its POD
 667     # also we do not want surprises in case JSON::XS is in the path
 668     # so make sure we get an always-working JSON::Any
 669     include => [qw(
 670       admin_script
 671       _json_xs_compatible_json_any
 672       id_shortener
 673       deploy
 674       test_pod
 675       test_podcoverage
 676       test_whitespace
 677       test_strictures
 678     )],
 679     req => {
 680       'ExtUtils::MakeMaker' => '6.64',
 681       'Module::Install'     => '1.06',
 682       'Pod::Inherit'        => '0.91',
 683     },
 684   },
 685
 686   dist_upload => {
 687     req => {
 688       'CPAN::Uploader' => '0.103001',
 689     },
 690   },
 691 };
 692
 693
 694
 695 ### Public API
 696
 697 sub import {
 698   my $class = shift;
 699
 700   if (@_) {
 701
 702     my $action = shift;
 703
 704     if ($action eq '-die_without') {
 705       my $err;
 706       {
 707         local $@;
 708         eval { $class->die_unless_req_ok_for(\@_); 1 }
 709           or $err = $@;
 710       }
 711       die "\n$err\n" if $err;
 712     }
 713     elsif ($action eq '-list_missing') {
 714       print $class->modreq_missing_for(\@_);
 715       print "\n";
 716       exit 0;
 717     }
 718     elsif ($action eq '-skip_all_without') {
 719
 720       # sanity check - make sure ->current_test is 0 and no plan has been declared
 721       do {
 722         local $@;
 723         defined eval {
 724           Test::Builder->new->current_test
 725             or
 726           Test::Builder->new->has_plan
 727         };
 728       } and croak("Unable to invoke -skip_all_without after testing has started");
 729
 730       if ( my $missing = $class->req_missing_for(\@_) ) {
 731
 732         die ("\nMandatory requirements not satisfied during release-testing: $missing\n\n")
 733           if $ENV{RELEASE_TESTING} and $class->_groups_to_reqs(\@_)->{release_testing_mandatory};
 734
 735         print "1..0 # SKIP requirements not satisfied: $missing\n";
 736         exit 0;
 737       }
 738     }
 739     elsif ($action =~ /^-/) {
 740       croak "Unknown import-time action '$action'";
 741     }
 742     else {
 743       croak "$class is not an exporter, unable to import '$action'";
 744     }
 745   }
 746
 747   1;
 748 }
 749
 750 sub unimport {
 751   croak( __PACKAGE__ . " does not implement unimport" );
 752 }
 753
 754 # OO for (mistakenly considered) ease of extensibility, not due to any need to
 755 # carry state of any sort. This API is currently used outside, so leave as-is.
 756 # FIXME - make sure to not propagate this further if module is extracted as a
 757 # standalone library - keep the stupidity to a DBIC-secific shim!
 758 #
 759 sub req_list_for {
 760   shift->_groups_to_reqs(shift)->{effective_modreqs};
 761 }
 762
 763 sub modreq_list_for {
 764   shift->_groups_to_reqs(shift)->{modreqs};
 765 }
 766
 767 sub req_group_list {
 768   +{ map
 769     { $_ => $_[0]->_groups_to_reqs($_) }
 770     grep { $_ !~ /^_/ } keys %$dbic_reqs
 771   }
 772 }
 773
 774 sub req_errorlist_for { shift->modreq_errorlist_for(shift) }  # deprecated
 775 sub modreq_errorlist_for {
 776   my ($self, $groups) = @_;
 777   $self->_errorlist_for_modreqs( $self->_groups_to_reqs($groups)->{modreqs} );
 778 }
 779
 780 sub req_ok_for {
 781   shift->req_missing_for(shift) ? 0 : 1;
 782 }
 783
 784 sub req_missing_for {
 785   my ($self, $groups) = @_;
 786
 787   my $reqs = $self->_groups_to_reqs($groups);
 788
 789   my $mods_missing = $reqs->{missing_envvars}
 790     ? $self->_list_physically_missing_modules( $reqs->{modreqs} )
 791     : $self->modreq_missing_for($groups)
 792   ;
 793
 794   return '' if
 795     ! $mods_missing
 796       and
 797     ! $reqs->{missing_envvars}
 798   ;
 799
 800   my @res = $mods_missing || ();
 801
 802   push @res, 'the following group(s) of environment variables: ' . join ' and ', sort map
 803     { __envvar_group_desc($_) }
 804     @{$reqs->{missing_envvars}}
 805   if $reqs->{missing_envvars};
 806
 807   return (
 808     ( join ' as well as ', @res )
 809       .
 810     ( $reqs->{modreqs_fully_documented} ? " (see @{[ ref $self || $self ]} documentation for details)" : '' ),
 811   );
 812 }
 813
 814 sub modreq_missing_for {
 815   my ($self, $groups) = @_;
 816
 817   my $reqs = $self->_groups_to_reqs($groups);
 818   my $modreq_errors = $self->_errorlist_for_modreqs($reqs->{modreqs})
 819     or return '';
 820
 821   join ' ', map
 822     { $reqs->{modreqs}{$_} ? "$_~$reqs->{modreqs}{$_}" : $_ }
 823     sort { lc($a) cmp lc($b) } keys %$modreq_errors
 824   ;
 825 }
 826
 827 my $tb;
 828 sub skip_without {
 829   my ($self, $groups) = @_;
 830
 831   $tb ||= do { local $@; eval { Test::Builder->new } }
 832     or croak "Calling skip_without() before loading Test::Builder makes no sense";
 833
 834   if ( my $err = $self->req_missing_for($groups) ) {
 835     my ($fn, $ln) = (caller(0))[1,2];
 836     $tb->skip("block in $fn around line $ln requires $err");
 837     local $^W = 0;
 838     last SKIP;
 839   }
 840
 841   1;
 842 }
 843
 844 sub die_unless_req_ok_for {
 845   if (my $err = shift->req_missing_for(shift) ) {
 846     die "Unable to continue due to missing requirements: $err\n";
 847   }
 848 }
 849
 850
 851
 852 ### Private functions
 853
 854 # potentially shorten group desc
 855 sub __envvar_group_desc {
 856   my @envs = @{$_[0]};
 857
 858   my (@res, $last_prefix);
 859   while (my $ev = shift @envs) {
 860     my ($pref, $sep, $suff) = split / ([\_\-]) (?= [^\_\-]+ \z )/x, $ev;
 861
 862     if ( defined $sep and ($last_prefix||'') eq $pref ) {
 863         push @res, "...${sep}${suff}"
 864     }
 865     else {
 866       push @res, $ev;
 867     }
 868
 869     $last_prefix = $pref if $sep;
 870   }
 871
 872   join '/', @res;
 873 }
 874
 875 my $groupname_re = qr/ [A-Z_a-z][0-9A-Z_a-z]* /x;
 876 my $modname_re = qr/ [A-Z_a-z] [0-9A-Z_a-z]* (?:::[0-9A-Z_a-z]+)* /x;
 877 my $modver_re = qr/ [0-9]+ (?: \. [0-9]+ )? /x;
 878
 879 # Expand includes from a random group in a specific order:
 880 # nonvariable groups first, then their includes, then the variable groups,
 881 # then their includes.
 882 # This allows reliably marking the rest of the mod reqs as variable (this is
 883 # also why variable includes are currently not allowed)
 884 sub __expand_includes {
 885   my ($groups, $seen) = @_;
 886
 887   # !! DIFFERENT !! behavior and return depending on invocation mode
 888   # (easier to recurse this way)
 889   my $is_toplevel = $seen
 890     ? 0
 891     : !! ($seen = {})
 892   ;
 893
 894   my ($res_per_type, $missing_envvars);
 895
 896   # breadth-first evaluation, with non-variable includes on top
 897   for my $g (@$groups) {
 898
 899     croak "Invalid requirement group name '$g': only ascii alphanumerics and _ are allowed"
 900       if $g !~ qr/ \A $groupname_re \z/x;
 901
 902     my $r = $dbic_reqs->{$g}
 903       or croak "Requirement group '$g' is not defined";
 904
 905     # always do this check *before* the $seen check
 906     croak "Group '$g' with variable effective_modreqs can not be specified as an 'include'"
 907       if ( $r->{env} and ! $is_toplevel );
 908
 909     next if $seen->{$g}++;
 910
 911     my $req_type = 'static';
 912
 913     if ( my @e = @{$r->{env}||[]} ) {
 914
 915       croak "Unexpected 'env' attribute under group '$g' (only allowed in test_* groups)"
 916         unless $g =~ /^test_/;
 917
 918       croak "Unexpected *odd* list in 'env' under group '$g'"
 919         if @e % 2;
 920
 921       # deconstruct the whole thing
 922       my (@group_envnames_list, $some_envs_required, $some_required_missing);
 923       while (@e) {
 924         push @group_envnames_list, my $envname = shift @e;
 925
 926         # env required or not
 927         next unless shift @e;
 928
 929         $some_envs_required ||= 1;
 930
 931         $some_required_missing ||= (
 932           ! defined $ENV{$envname}
 933             or
 934           ! length $ENV{$envname}
 935         );
 936       }
 937
 938       croak "None of the envvars in group '$g' declared as required, making the requirement moot"
 939         unless $some_envs_required;
 940
 941       if ($some_required_missing) {
 942         push @{$missing_envvars->{$g}}, \@group_envnames_list;
 943         $req_type = 'variable';
 944       }
 945     }
 946
 947     push @{$res_per_type->{"base_${req_type}"}}, $g;
 948
 949     if (my $i = $dbic_reqs->{$g}{include}) {
 950       $i = [ $i ] unless ref $i eq 'ARRAY';
 951
 952       croak "Malformed 'include' for group '$g': must be another existing group name or arrayref of existing group names"
 953         unless @$i;
 954
 955       push @{$res_per_type->{"incs_${req_type}"}}, @$i;
 956     }
 957   }
 958
 959   my @ret = map {
 960     @{ $res_per_type->{"base_${_}"} || [] },
 961     ( $res_per_type->{"incs_${_}"} ? __expand_includes( $res_per_type->{"incs_${_}"}, $seen ) : () ),
 962   } qw(static variable);
 963
 964   return ! $is_toplevel ? @ret : do {
 965     my $rv = {};
 966     $rv->{$_} = {
 967       idx => 1 + keys %$rv,
 968       missing_envvars => $missing_envvars->{$_},
 969     } for @ret;
 970     $rv->{$_}{user_requested} = 1 for @$groups;
 971     $rv;
 972   };
 973 }
 974
 975 ### Private OO API
 976 our %req_unavailability_cache;
 977
 978 # this method is just a lister and envvar/metadata checker - it does not try to load anything
 979 sub _groups_to_reqs {
 980   my ($self, $want) = @_;
 981
 982   $want = [ $want || () ]
 983     unless ref $want eq 'ARRAY';
 984
 985   croak "@{[ (caller(1))[3] ]}() expects a requirement group name or arrayref of group names"
 986     unless @$want;
 987
 988   my $ret = {
 989     modreqs => {},
 990     modreqs_fully_documented => 1,
 991   };
 992
 993   my $groups;
 994   for my $piece (@$want) {
 995     if ($piece =~ qr/ \A $groupname_re \z /x) {
 996       push @$groups, $piece;
 997     }
 998     elsif ( my ($mod, $ver) = $piece =~ qr/ \A ($modname_re) \>\= ($modver_re) \z /x ) {
 999       croak "Ad hoc module specification lists '$mod' twice"
1000         if exists $ret->{modreqs}{$mod};
1001
1002       croak "Ad hoc module specification '${mod} >= $ver' (or greater) not listed in the test_adhoc optdep group" if (
1003         ! defined $dbic_reqs->{test_adhoc}{req}{$mod}
1004           or
1005         $dbic_reqs->{test_adhoc}{req}{$mod} < $ver
1006       );
1007
1008       $ret->{modreqs}{$mod} = $ver;
1009       $ret->{modreqs_fully_documented} = 0;
1010     }
1011     else {
1012       croak "Unsupported argument '$piece' supplied to @{[ (caller(1))[3] ]}()"
1013     }
1014   }
1015
1016   my $all_groups = __expand_includes($groups);
1017
1018   # pre-assemble list of augmentations, perform basic sanity checks
1019   # Note that below we *DO NOT* respect the source/target reationship, but
1020   # instead always default to augment the "later" group
1021   # This is done so that the "stable/variable" boundary keeps working as
1022   # expected
1023   my $augmentations;
1024   for my $requesting_group (keys %$all_groups) {
1025     if (my $ag = $dbic_reqs->{$requesting_group}{augment}) {
1026       for my $target_group (keys %$ag) {
1027
1028         croak "Group '$requesting_group' claims to augment a non-existent group '$target_group'"
1029           unless $dbic_reqs->{$target_group};
1030
1031         croak "Augmentation combined with variable effective_modreqs currently unsupported for group '$requesting_group'"
1032           if $dbic_reqs->{$requesting_group}{env};
1033
1034         croak "Augmentation of group '$target_group' with variable effective_modreqs unsupported (requested by '$requesting_group')"
1035           if $dbic_reqs->{$target_group}{env};
1036
1037         if (my @foreign = grep { $_ ne 'req' } keys %{$ag->{$target_group}} ) {
1038           croak "Only 'req' augmentations are currently supported (group '$requesting_group' attempts to alter '$foreign[0]' of group '$target_group'";
1039         }
1040
1041         $ret->{augments}{$target_group} = 1;
1042
1043         # no augmentation for stuff that hasn't been selected
1044         if ( $all_groups->{$target_group} and my $ar = $ag->{$target_group}{req} ) {
1045           push @{$augmentations->{
1046             ( $all_groups->{$requesting_group}{idx} < $all_groups->{$target_group}{idx} )
1047               ? $target_group
1048               : $requesting_group
1049           }}, $ar;
1050         }
1051       }
1052     }
1053   }
1054
1055   for my $group (sort { $all_groups->{$a}{idx} <=> $all_groups->{$b}{idx} } keys %$all_groups ) {
1056
1057     my $group_reqs = $dbic_reqs->{$group}{req};
1058
1059     # sanity-check
1060     for my $req_bag ($group_reqs, @{ $augmentations->{$group} || [] } ) {
1061       for (keys %$req_bag) {
1062
1063         $_ =~ / \A $modname_re \z /x
1064           or croak "Requirement '$_' in group '$group' is not a valid module name";
1065
1066         # !!!DO NOT CHANGE!!!
1067         # remember - version.pm may not be available on the system
1068         croak "Requirement '$_' in group '$group' specifies an invalid version '$req_bag->{$_}' (only plain non-underscored floating point decimals are supported)"
1069           if ( ($req_bag->{$_}||0) !~ qr/ \A $modver_re \z /x );
1070       }
1071     }
1072
1073     if (my $e = $all_groups->{$group}{missing_envvars}) {
1074       push @{$ret->{missing_envvars}}, @$e;
1075     }
1076
1077     # assemble into the final ret
1078     for my $type (
1079       'modreqs',
1080       ( $ret->{missing_envvars} ? () : 'effective_modreqs' ),
1081     ) {
1082       for my $req_bag ($group_reqs, @{ $augmentations->{$group} || [] } ) {
1083         for my $mod (keys %$req_bag) {
1084
1085           $ret->{$type}{$mod} = $req_bag->{$mod}||0 if (
1086
1087             ! exists $ret->{$type}{$mod}
1088               or
1089             # we sanitized the version to be numeric above - we can just -gt it
1090             ($req_bag->{$mod}||0) > $ret->{$type}{$mod}
1091
1092           );
1093         }
1094       }
1095     }
1096
1097     $ret->{modreqs_fully_documented} &&= !!$dbic_reqs->{$group}{pod}
1098       if $all_groups->{$group}{user_requested};
1099
1100     $ret->{release_testing_mandatory} ||= !!$dbic_reqs->{$group}{release_testing_mandatory};
1101   }
1102
1103   return $ret;
1104 }
1105
1106
1107 # this method tries to find/load specified modreqs and returns a hashref of
1108 # module/loaderror pairs for anything that failed
1109 sub _errorlist_for_modreqs {
1110   # args supposedly already went through _groups_to_reqs and are therefore sanitized
1111   # safe to eval at will
1112   my ($self, $reqs) = @_;
1113
1114   my $ret;
1115
1116   for my $m ( keys %$reqs ) {
1117     my $v = $reqs->{$m};
1118
1119     if (! exists $req_unavailability_cache{$m}{$v} ) {
1120       local $@;
1121       eval( "require $m;" . ( $v ? "$m->VERSION(q($v))" : '' ) );
1122       $req_unavailability_cache{$m}{$v} = $@;
1123     }
1124
1125     $ret->{$m} = $req_unavailability_cache{$m}{$v}
1126       if $req_unavailability_cache{$m}{$v};
1127   }
1128
1129   $ret;
1130 }
1131
1132 # Unlike the above DO NOT try to load anything
1133 # This is executed when some needed envvars are not available
1134 # which in turn means a module load will never be reached anyway
1135 # This is important because some modules (especially DBDs) can be
1136 # *really* fickle when a require() is attempted, with pretty confusing
1137 # side-effects (especially on windows)
1138 sub _list_physically_missing_modules {
1139   my ($self, $modreqs) = @_;
1140
1141   # in case there is a coderef in @INC there is nothing we can definitively prove
1142   # so short circuit directly
1143   return '' if grep { length ref $_ } @INC;
1144
1145   my @definitely_missing;
1146   for my $mod (keys %$modreqs) {
1147     (my $fn = $mod . '.pm') =~ s|::|/|g;
1148
1149     push @definitely_missing, $mod unless grep
1150       # this should work on any combination of slashes
1151       { $_ and -d $_ and -f "$_/$fn" and -r "$_/$fn" }
1152       @INC
1153     ;
1154   }
1155
1156   join ' ', map
1157     { $modreqs->{$_} ? "$_~$modreqs->{$_}" : $_ }
1158     sort { lc($a) cmp lc($b) } @definitely_missing
1159   ;
1160 }
1161
1162
1163 # This is to be called by the author only (automatically in Makefile.PL)
1164 sub _gen_pod {
1165   my ($class, $distver, $pod_dir) = @_;
1166
1167   die "No POD root dir supplied" unless $pod_dir;
1168
1169   $distver ||=
1170     eval { require DBIx::Class; DBIx::Class->VERSION; }
1171       ||
1172     die
1173 "\n\n---------------------------------------------------------------------\n" .
1174 'Unable to load core DBIx::Class module to determine current version, '.
1175 'possibly due to missing dependencies. Author-mode autodocumentation ' .
1176 "halted\n\n" . $@ .
1177 "\n\n---------------------------------------------------------------------\n"
1178   ;
1179
1180   # do not ask for a recent version, use 1.x API calls
1181   # this *may* execute on a smoker with old perl or whatnot
1182   require File::Path;
1183
1184   (my $modfn = __PACKAGE__ . '.pm') =~ s|::|/|g;
1185
1186   (my $podfn = "$pod_dir/$modfn") =~ s/\.pm$/\.pod/;
1187   (my $dir = $podfn) =~ s|/[^/]+$||;
1188
1189   File::Path::mkpath([$dir]);
1190
1191   my $sqltver = $class->req_list_for('deploy')->{'SQL::Translator'}
1192     or die "Hrmm? No sqlt dep?";
1193
1194
1195   my @chunks;
1196
1197 #@@
1198 #@@ HEADER
1199 #@@
1200   push @chunks, <<"EOC";
1201 #########################################################################
1202 #####################  A U T O G E N E R A T E D ########################
1203 #########################################################################
1204 #
1205 # The contents of this POD file are auto-generated.  Any changes you make
1206 # will be lost. If you need to change the generated text edit _gen_pod()
1207 # at the end of $modfn
1208 #
1209
1210 =head1 NAME
1211
1212 $class - Optional module dependency specifications (for module authors)
1213 EOC
1214
1215
1216 #@@
1217 #@@ SYNOPSIS HEADING
1218 #@@
1219   push @chunks, <<"EOC";
1220 =head1 SYNOPSIS
1221
1222 Somewhere in your build-file (e.g. L<ExtUtils::MakeMaker>'s F<Makefile.PL>):
1223
1224   ...
1225
1226   \$EUMM_ARGS{CONFIGURE_REQUIRES} = {
1227     \%{ \$EUMM_ARGS{CONFIGURE_REQUIRES} || {} },
1228     'DBIx::Class' => '$distver',
1229   };
1230
1231   ...
1232
1233   my %DBIC_DEPLOY_AND_ORACLE_DEPS = %{ eval {
1234     require $class;
1235     $class->req_list_for([qw( deploy rdbms_oracle icdt )]);
1236   } || {} };
1237
1238   \$EUMM_ARGS{PREREQ_PM} = {
1239     \%DBIC_DEPLOY_AND_ORACLE_DEPS,
1240     \%{ \$EUMM_ARGS{PREREQ_PM} || {} },
1241   };
1242
1243   ...
1244
1245   ExtUtils::MakeMaker::WriteMakefile(\%EUMM_ARGS);
1246
1247 B<Note>: The C<eval> protection within the example is due to support for
1248 requirements during L<the C<configure> build phase|CPAN::Meta::Spec/Phases>
1249 not being available on a sufficient portion of production installations of
1250 Perl. Robust support for such dependency requirements is available in the
1251 L<CPAN> installer only since version C<1.94_56> first made available for
1252 production with perl version C<5.12>. It is the belief of the current
1253 maintainer that support for requirements during the C<configure> build phase
1254 will not be sufficiently ubiquitous until the B<year 2020> at the earliest,
1255 hence the extra care demonstrated above. It should also be noted that some
1256 3rd party installers (e.g. L<cpanminus|App::cpanminus>) do the right thing
1257 with configure requirements independent from the versions of perl and CPAN
1258 available.
1259 EOC
1260
1261
1262 #@@
1263 #@@ DESCRIPTION HEADING
1264 #@@
1265   push @chunks, <<'EOC';
1266 =head1 DESCRIPTION
1267
1268 Some of the less-frequently used features of L<DBIx::Class> have external
1269 module dependencies on their own. In order not to burden the average user
1270 with modules they will never use, these optional dependencies are not included
1271 in the base Makefile.PL. Instead an exception with a descriptive message is
1272 thrown when a specific feature can't find one or several modules required for
1273 its operation. This module is the central holding place for the current list
1274 of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
1275 authors alike.
1276
1277 Dependencies are organized in L<groups|/CURRENT REQUIREMENT GROUPS> where each
1278 group can list one or more required modules, with an optional minimum version
1279 (or 0 for any version). In addition groups prefixed with C<test_> can specify
1280 a set of environment variables, some (or all) of which are marked as required
1281 for the group to be considered by L</req_list_for>
1282
1283 Each group name (or a combination thereof) can be used in the
1284 L<public methods|/METHODS> as described below.
1285 EOC
1286
1287
1288 #@@
1289 #@@ REQUIREMENT GROUPLIST HEADING
1290 #@@
1291   push @chunks, '=head1 CURRENT REQUIREMENT GROUPS';
1292
1293   my $standalone_info;
1294
1295   for my $group (sort keys %$dbic_reqs) {
1296
1297     my $info = $standalone_info->{$group} ||= $class->_groups_to_reqs($group);
1298
1299     next unless (
1300       $info->{modreqs_fully_documented}
1301         and
1302       ( $info->{augments} or $info->{modreqs} )
1303     );
1304
1305     my $p = $dbic_reqs->{$group}{pod};
1306
1307     push @chunks, (
1308       "=head2 $p->{title}",
1309       "=head3 $group",
1310       $p->{desc},
1311       '=over',
1312     );
1313
1314     if ( keys %{ $info->{modreqs}||{} } ) {
1315       push @chunks, map
1316         { "=item * $_" . ($info->{modreqs}{$_} ? " >= $info->{modreqs}{$_}" : '') }
1317         ( sort keys %{ $info->{modreqs} } )
1318       ;
1319     }
1320     else {
1321       push @chunks, '=item * No standalone requirements',
1322     }
1323
1324     push @chunks, '=back';
1325
1326     for my $ag ( sort keys %{ $info->{augments} || {} } ) {
1327       my $ag_info = $standalone_info->{$ag} ||= $class->_groups_to_reqs($ag);
1328
1329       my $newreqs = $class->modreq_list_for([ $group, $ag ]);
1330       for (keys %$newreqs) {
1331         delete $newreqs->{$_} if (
1332           ( defined $info->{modreqs}{$_}    and $info->{modreqs}{$_}    == $newreqs->{$_} )
1333             or
1334           ( defined $ag_info->{modreqs}{$_} and $ag_info->{modreqs}{$_} == $newreqs->{$_} )
1335         );
1336       }
1337
1338       if (keys %$newreqs) {
1339         push @chunks, (
1340           "Combined with L</$ag> additionally requires:",
1341           '=over',
1342           ( map
1343             { "=item * $_" . ($newreqs->{$_} ? " >= $newreqs->{$_}" : '') }
1344             ( sort keys %$newreqs )
1345           ),
1346           '=back',
1347         );
1348       }
1349     }
1350   }
1351
1352
1353 #@@
1354 #@@ API DOCUMENTATION HEADING
1355 #@@
1356   push @chunks, <<'EOC';
1357
1358 =head1 IMPORT-LIKE ACTIONS
1359
1360 Even though this module is not an L<Exporter>, it recognizes several C<actions>
1361 supplied to its C<import> method.
1362
1363 =head2 -skip_all_without
1364
1365 =over
1366
1367 =item Arguments: @group_names
1368
1369 =back
1370
1371 A convenience wrapper for use during testing:
1372 EOC
1373
1374   push @chunks, " use $class -skip_all_without => qw(admin test_rdbms_mysql);";
1375
1376   push @chunks, 'Roughly equivalent to the following code:';
1377
1378   push @chunks, sprintf <<'EOS', ($class) x 2;
1379
1380  BEGIN {
1381    require %s;
1382    if ( my $missing = %s->req_missing_for(\@group_names_) ) {
1383      print "1..0 # SKIP requirements not satisfied: $missing\n";
1384      exit 0;
1385    }
1386  }
1387 EOS
1388
1389   push @chunks, <<'EOC';
1390
1391 It also takes into account the C<RELEASE_TESTING> environment variable and
1392 behaves like L</-die_without> for any requirement groups marked as
1393 C<release_testing_mandatory>.
1394
1395 =head2 -die_without
1396
1397 =over
1398
1399 =item Arguments: @group_names
1400
1401 =back
1402
1403 A convenience wrapper around L</die_unless_req_ok_for>:
1404 EOC
1405
1406   push @chunks, " use $class -die_without => qw(deploy admin);";
1407
1408   push @chunks, <<'EOC';
1409
1410 =head2 -list_missing
1411
1412 =over
1413
1414 =item Arguments: @group_names
1415
1416 =back
1417
1418 A convenience wrapper around L</modreq_missing_for>:
1419
1420  perl -Ilib -MDBIx::Class::Optional::Dependencies=-list_missing,deploy,admin | cpanm
1421
1422 =head1 METHODS
1423
1424 =head2 req_group_list
1425
1426 =over
1427
1428 =item Arguments: none
1429
1430 =item Return Value: \%list_of_requirement_groups
1431
1432 =back
1433
1434 This method should be used by DBIx::Class packagers, to get a hashref of all
1435 dependencies B<keyed> by dependency group. Each key (group name), or a combination
1436 thereof (as an arrayref) can be supplied to the methods below.
1437 The B<values> of the returned hash are currently a set of options B<without a
1438 well defined structure>. If you have use for any of the contents - contact the
1439 maintainers, instead of treating this as public (left alone stable) API.
1440
1441 =head2 req_list_for
1442
1443 =over
1444
1445 =item Arguments: $group_name | \@group_names
1446
1447 =item Return Value: \%set_of_module_version_pairs
1448
1449 =back
1450
1451 This method should be used by DBIx::Class extension authors, to determine the
1452 version of modules a specific set of features requires for this version of
1453 DBIx::Class (regardless of their availability on the system).
1454 See the L</SYNOPSIS> for a real-world example.
1455
1456 When handling C<test_*> groups this method behaves B<differently> from
1457 L</modreq_list_for> below (and is the only such inconsistency among the
1458 C<req_*> methods). If a particular group declares as requirements some
1459 C<environment variables> and these requirements are not satisfied (the envvars
1460 are unset) - then the C<module requirements> of this group are not included in
1461 the returned list.
1462
1463 =head2 modreq_list_for
1464
1465 =over
1466
1467 =item Arguments: $group_name | \@group_names
1468
1469 =item Return Value: \%set_of_module_version_pairs
1470
1471 =back
1472
1473 Same as L</req_list_for> but does not take into consideration any
1474 C<environment variable requirements> - returns just the list of required
1475 modules.
1476
1477 =head2 req_ok_for
1478
1479 =over
1480
1481 =item Arguments: $group_name | \@group_names
1482
1483 =item Return Value: 1|0
1484
1485 =back
1486
1487 Returns true or false depending on whether all modules/envvars required by
1488 the group(s) are loadable/set on the system.
1489
1490 =head2 req_missing_for
1491
1492 =over
1493
1494 =item Arguments: $group_name | \@group_names
1495
1496 =item Return Value: $error_message_string
1497
1498 =back
1499
1500 Returns a single-line string suitable for inclusion in larger error messages.
1501 This method would normally be used by DBIx::Class core features, to indicate to
1502 the user that they need to install specific modules and/or set specific
1503 environment variables before being able to use a specific feature set.
1504
1505 For example if some of the requirements for C<deploy> are not available,
1506 the returned string could look like:
1507 EOC
1508
1509   push @chunks, qq{ "SQL::Translator~$sqltver" (see $class documentation for details)};
1510
1511   push @chunks, <<'EOC';
1512 The author is expected to prepend the necessary text to this message before
1513 returning the actual error seen by the user. See also L</modreq_missing_for>
1514
1515 =head2 modreq_missing_for
1516
1517 =over
1518
1519 =item Arguments: $group_name | \@group_names
1520
1521 =item Return Value: $error_message_string
1522
1523 =back
1524
1525 Same as L</req_missing_for> except that the error string is guaranteed to be
1526 either empty, or contain a set of module requirement specifications suitable
1527 for piping to e.g. L<cpanminus|App::cpanminus>. The method explicitly does not
1528 attempt to validate the state of required environment variables (if any).
1529
1530 For instance if some of the requirements for C<deploy> are not available,
1531 the returned string could look like:
1532 EOC
1533
1534   push @chunks, qq{ "SQL::Translator~$sqltver"};
1535
1536   push @chunks, <<'EOC';
1537
1538 See also L</-list_missing>.
1539
1540 =head2 skip_without
1541
1542 =over
1543
1544 =item Arguments: $group_name | \@group_names
1545
1546 =back
1547
1548 A convenience wrapper around L<skip|Test::More/SKIP>. It does not take neither
1549 a reason (it is generated by L</req_missing_for>) nor an amount of skipped tests
1550 (it is always C<1>, thus mandating unconditional use of
1551 L<done_testing|Test::More/done_testing>). Most useful in combination with ad hoc
1552 requirement specifications:
1553 EOC
1554
1555   push @chunks, <<EOC;
1556   SKIP: {
1557     $class->skip_without([ deploy YAML>=0.90 ]);
1558
1559     ...
1560   }
1561 EOC
1562
1563   push @chunks, <<'EOC';
1564
1565 =head2 die_unless_req_ok_for
1566
1567 =over
1568
1569 =item Arguments: $group_name | \@group_names
1570
1571 =back
1572
1573 Checks if L</req_ok_for> passes for the supplied group(s), and
1574 in case of failure throws an exception including the information
1575 from L</req_missing_for>. See also L</-die_without>.
1576
1577 =head2 modreq_errorlist_for
1578
1579 =over
1580
1581 =item Arguments: $group_name | \@group_names
1582
1583 =item Return Value: \%set_of_loaderrors_per_module
1584
1585 =back
1586
1587 Returns a hashref containing the actual errors that occurred while attempting
1588 to load each module in the requirement group(s).
1589
1590 =head2 req_errorlist_for
1591
1592 Deprecated method name, equivalent (via proxy) to L</modreq_errorlist_for>.
1593
1594 EOC
1595
1596 #@@
1597 #@@ FOOTER
1598 #@@
1599   push @chunks, <<'EOC';
1600 =head1 FURTHER QUESTIONS?
1601
1602 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
1603
1604 =head1 COPYRIGHT AND LICENSE
1605
1606 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
1607 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
1608 redistribute it and/or modify it under the same terms as the
1609 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
1610 EOC
1611
1612   eval {
1613     open (my $fh, '>', $podfn) or die;
1614     print $fh join ("\n\n", @chunks) or die;
1615     print $fh "\n" or die;
1616     close ($fh) or die;
1617   } or croak( "Unable to write $podfn: " . ( $! || $@ || 'unknown error') );
1618 }
1619
1620 1;