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