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( admin_script _json_xs_compatible_json_any )],
 676     req => {
 677       'ExtUtils::MakeMaker' => '6.64',
 678       'Pod::Inherit'        => '0.91',
 679     },
 680   },
 681
 682   dist_upload => {
 683     req => {
 684       'CPAN::Uploader' => '0.103001',
 685     },
 686   },
 687 };
 688
 689
 690
 691 ### Public API
 692
 693 sub import {
 694   my $class = shift;
 695
 696   if (@_) {
 697
 698     my $action = shift;
 699
 700     if ($action eq '-die_without') {
 701       my $err;
 702       {
 703         local $@;
 704         eval { $class->die_unless_req_ok_for(\@_); 1 }
 705           or $err = $@;
 706       }
 707       die "\n$err\n" if $err;
 708     }
 709     elsif ($action eq '-list_missing') {
 710       print $class->modreq_missing_for(\@_);
 711       print "\n";
 712       exit 0;
 713     }
 714     elsif ($action eq '-skip_all_without') {
 715
 716       # sanity check - make sure ->current_test is 0 and no plan has been declared
 717       do {
 718         local $@;
 719         defined eval {
 720           Test::Builder->new->current_test
 721             or
 722           Test::Builder->new->has_plan
 723         };
 724       } and croak("Unable to invoke -skip_all_without after testing has started");
 725
 726       if ( my $missing = $class->req_missing_for(\@_) ) {
 727
 728         die ("\nMandatory requirements not satisfied during release-testing: $missing\n\n")
 729           if $ENV{RELEASE_TESTING} and $class->_groups_to_reqs(\@_)->{release_testing_mandatory};
 730
 731         print "1..0 # SKIP requirements not satisfied: $missing\n";
 732         exit 0;
 733       }
 734     }
 735     elsif ($action =~ /^-/) {
 736       croak "Unknown import-time action '$action'";
 737     }
 738     else {
 739       croak "$class is not an exporter, unable to import '$action'";
 740     }
 741   }
 742
 743   1;
 744 }
 745
 746 sub unimport {
 747   croak( __PACKAGE__ . " does not implement unimport" );
 748 }
 749
 750 # OO for (mistakenly considered) ease of extensibility, not due to any need to
 751 # carry state of any sort. This API is currently used outside, so leave as-is.
 752 # FIXME - make sure to not propagate this further if module is extracted as a
 753 # standalone library - keep the stupidity to a DBIC-secific shim!
 754 #
 755 sub req_list_for {
 756   shift->_groups_to_reqs(shift)->{effective_modreqs};
 757 }
 758
 759 sub modreq_list_for {
 760   shift->_groups_to_reqs(shift)->{modreqs};
 761 }
 762
 763 sub req_group_list {
 764   +{ map
 765     { $_ => $_[0]->_groups_to_reqs($_) }
 766     grep { $_ !~ /^_/ } keys %$dbic_reqs
 767   }
 768 }
 769
 770 sub req_errorlist_for { shift->modreq_errorlist_for(shift) }  # deprecated
 771 sub modreq_errorlist_for {
 772   my ($self, $groups) = @_;
 773   $self->_errorlist_for_modreqs( $self->_groups_to_reqs($groups)->{modreqs} );
 774 }
 775
 776 sub req_ok_for {
 777   shift->req_missing_for(shift) ? 0 : 1;
 778 }
 779
 780 sub req_missing_for {
 781   my ($self, $groups) = @_;
 782
 783   my $reqs = $self->_groups_to_reqs($groups);
 784
 785   my $mods_missing = $reqs->{missing_envvars}
 786     ? $self->_list_physically_missing_modules( $reqs->{modreqs} )
 787     : $self->modreq_missing_for($groups)
 788   ;
 789
 790   return '' if
 791     ! $mods_missing
 792       and
 793     ! $reqs->{missing_envvars}
 794   ;
 795
 796   my @res = $mods_missing || ();
 797
 798   push @res, 'the following group(s) of environment variables: ' . join ' and ', sort map
 799     { __envvar_group_desc($_) }
 800     @{$reqs->{missing_envvars}}
 801   if $reqs->{missing_envvars};
 802
 803   return (
 804     ( join ' as well as ', @res )
 805       .
 806     ( $reqs->{modreqs_fully_documented} ? " (see @{[ ref $self || $self ]} documentation for details)" : '' ),
 807   );
 808 }
 809
 810 sub modreq_missing_for {
 811   my ($self, $groups) = @_;
 812
 813   my $reqs = $self->_groups_to_reqs($groups);
 814   my $modreq_errors = $self->_errorlist_for_modreqs($reqs->{modreqs})
 815     or return '';
 816
 817   join ' ', map
 818     { $reqs->{modreqs}{$_} ? "$_~$reqs->{modreqs}{$_}" : $_ }
 819     sort { lc($a) cmp lc($b) } keys %$modreq_errors
 820   ;
 821 }
 822
 823 my $tb;
 824 sub skip_without {
 825   my ($self, $groups) = @_;
 826
 827   $tb ||= do { local $@; eval { Test::Builder->new } }
 828     or croak "Calling skip_without() before loading Test::Builder makes no sense";
 829
 830   if ( my $err = $self->req_missing_for($groups) ) {
 831     my ($fn, $ln) = (caller(0))[1,2];
 832     $tb->skip("block in $fn around line $ln requires $err");
 833     local $^W = 0;
 834     last SKIP;
 835   }
 836
 837   1;
 838 }
 839
 840 sub die_unless_req_ok_for {
 841   if (my $err = shift->req_missing_for(shift) ) {
 842     die "Unable to continue due to missing requirements: $err\n";
 843   }
 844 }
 845
 846
 847
 848 ### Private functions
 849
 850 # potentially shorten group desc
 851 sub __envvar_group_desc {
 852   my @envs = @{$_[0]};
 853
 854   my (@res, $last_prefix);
 855   while (my $ev = shift @envs) {
 856     my ($pref, $sep, $suff) = split / ([\_\-]) (?= [^\_\-]+ \z )/x, $ev;
 857
 858     if ( defined $sep and ($last_prefix||'') eq $pref ) {
 859         push @res, "...${sep}${suff}"
 860     }
 861     else {
 862       push @res, $ev;
 863     }
 864
 865     $last_prefix = $pref if $sep;
 866   }
 867
 868   join '/', @res;
 869 }
 870
 871 my $groupname_re = qr/ [a-z_] [0-9_a-z]* /x;
 872 my $modname_re = qr/ [A-Z_a-z] [0-9A-Z_a-z]* (?:::[0-9A-Z_a-z]+)* /x;
 873 my $modver_re = qr/ [0-9]+ (?: \. [0-9]+ )? /x;
 874
 875 # Expand includes from a random group in a specific order:
 876 # nonvariable groups first, then their includes, then the variable groups,
 877 # then their includes.
 878 # This allows reliably marking the rest of the mod reqs as variable (this is
 879 # also why variable includes are currently not allowed)
 880 sub __expand_includes {
 881   my ($groups, $seen) = @_;
 882
 883   # !! DIFFERENT !! behavior and return depending on invocation mode
 884   # (easier to recurse this way)
 885   my $is_toplevel = $seen
 886     ? 0
 887     : !! ($seen = {})
 888   ;
 889
 890   my ($res_per_type, $missing_envvars);
 891
 892   # breadth-first evaluation, with non-variable includes on top
 893   for my $g (@$groups) {
 894
 895     croak "Invalid requirement group name '$g': only ascii alphanumerics and _ are allowed"
 896       if $g !~ qr/ \A $groupname_re \z/x;
 897
 898     my $r = $dbic_reqs->{$g}
 899       or croak "Requirement group '$g' is not defined";
 900
 901     # always do this check *before* the $seen check
 902     croak "Group '$g' with variable effective_modreqs can not be specified as an 'include'"
 903       if ( $r->{env} and ! $is_toplevel );
 904
 905     next if $seen->{$g}++;
 906
 907     my $req_type = 'static';
 908
 909     if ( my @e = @{$r->{env}||[]} ) {
 910
 911       croak "Unexpected 'env' attribute under group '$g' (only allowed in test_* groups)"
 912         unless $g =~ /^test_/;
 913
 914       croak "Unexpected *odd* list in 'env' under group '$g'"
 915         if @e % 2;
 916
 917       # deconstruct the whole thing
 918       my (@group_envnames_list, $some_envs_required, $some_required_missing);
 919       while (@e) {
 920         push @group_envnames_list, my $envname = shift @e;
 921
 922         # env required or not
 923         next unless shift @e;
 924
 925         $some_envs_required ||= 1;
 926
 927         $some_required_missing ||= (
 928           ! defined $ENV{$envname}
 929             or
 930           ! length $ENV{$envname}
 931         );
 932       }
 933
 934       croak "None of the envvars in group '$g' declared as required, making the requirement moot"
 935         unless $some_envs_required;
 936
 937       if ($some_required_missing) {
 938         push @{$missing_envvars->{$g}}, \@group_envnames_list;
 939         $req_type = 'variable';
 940       }
 941     }
 942
 943     push @{$res_per_type->{"base_${req_type}"}}, $g;
 944
 945     if (my $i = $dbic_reqs->{$g}{include}) {
 946       $i = [ $i ] unless ref $i eq 'ARRAY';
 947
 948       croak "Malformed 'include' for group '$g': must be another existing group name or arrayref of existing group names"
 949         unless @$i;
 950
 951       push @{$res_per_type->{"incs_${req_type}"}}, @$i;
 952     }
 953   }
 954
 955   my @ret = map {
 956     @{ $res_per_type->{"base_${_}"} || [] },
 957     ( $res_per_type->{"incs_${_}"} ? __expand_includes( $res_per_type->{"incs_${_}"}, $seen ) : () ),
 958   } qw(static variable);
 959
 960   return ! $is_toplevel ? @ret : do {
 961     my $rv = {};
 962     $rv->{$_} = {
 963       idx => 1 + keys %$rv,
 964       missing_envvars => $missing_envvars->{$_},
 965     } for @ret;
 966     $rv->{$_}{user_requested} = 1 for @$groups;
 967     $rv;
 968   };
 969 }
 970
 971 ### Private OO API
 972 our %req_unavailability_cache;
 973
 974 # this method is just a lister and envvar/metadata checker - it does not try to load anything
 975 sub _groups_to_reqs {
 976   my ($self, $want) = @_;
 977
 978   $want = [ $want || () ]
 979     unless ref $want eq 'ARRAY';
 980
 981   croak "@{[ (caller(1))[3] ]}() expects a requirement group name or arrayref of group names"
 982     unless @$want;
 983
 984   my $ret = {
 985     modreqs => {},
 986     modreqs_fully_documented => 1,
 987   };
 988
 989   my $groups;
 990   for my $piece (@$want) {
 991     if ($piece =~ qr/ \A $groupname_re \z /x) {
 992       push @$groups, $piece;
 993     }
 994     elsif ( my ($mod, $ver) = $piece =~ qr/ \A ($modname_re) \>\= ($modver_re) \z /x ) {
 995       croak "Ad hoc module specification lists '$mod' twice"
 996         if exists $ret->{modreqs}{$mod};
 997
 998       croak "Ad hoc module specification '${mod} >= $ver' (or greater) not listed in the test_adhoc optdep group" if (
 999         ! defined $dbic_reqs->{test_adhoc}{req}{$mod}
1000           or
1001         $dbic_reqs->{test_adhoc}{req}{$mod} < $ver
1002       );
1003
1004       $ret->{modreqs}{$mod} = $ver;
1005       $ret->{modreqs_fully_documented} = 0;
1006     }
1007     else {
1008       croak "Unsupported argument '$piece' supplied to @{[ (caller(1))[3] ]}()"
1009     }
1010   }
1011
1012   my $all_groups = __expand_includes($groups);
1013
1014   # pre-assemble list of augmentations, perform basic sanity checks
1015   # Note that below we *DO NOT* respect the source/target reationship, but
1016   # instead always default to augment the "later" group
1017   # This is done so that the "stable/variable" boundary keeps working as
1018   # expected
1019   my $augmentations;
1020   for my $requesting_group (keys %$all_groups) {
1021     if (my $ag = $dbic_reqs->{$requesting_group}{augment}) {
1022       for my $target_group (keys %$ag) {
1023
1024         croak "Group '$requesting_group' claims to augment a non-existent group '$target_group'"
1025           unless $dbic_reqs->{$target_group};
1026
1027         croak "Augmentation combined with variable effective_modreqs currently unsupported for group '$requesting_group'"
1028           if $dbic_reqs->{$requesting_group}{env};
1029
1030         croak "Augmentation of group '$target_group' with variable effective_modreqs unsupported (requested by '$requesting_group')"
1031           if $dbic_reqs->{$target_group}{env};
1032
1033         if (my @foreign = grep { $_ ne 'req' } keys %{$ag->{$target_group}} ) {
1034           croak "Only 'req' augmentations are currently supported (group '$requesting_group' attempts to alter '$foreign[0]' of group '$target_group'";
1035         }
1036
1037         $ret->{augments}{$target_group} = 1;
1038
1039         # no augmentation for stuff that hasn't been selected
1040         if ( $all_groups->{$target_group} and my $ar = $ag->{$target_group}{req} ) {
1041           push @{$augmentations->{
1042             ( $all_groups->{$requesting_group}{idx} < $all_groups->{$target_group}{idx} )
1043               ? $target_group
1044               : $requesting_group
1045           }}, $ar;
1046         }
1047       }
1048     }
1049   }
1050
1051   for my $group (sort { $all_groups->{$a}{idx} <=> $all_groups->{$b}{idx} } keys %$all_groups ) {
1052
1053     my $group_reqs = $dbic_reqs->{$group}{req};
1054
1055     # sanity-check
1056     for my $req_bag ($group_reqs, @{ $augmentations->{$group} || [] } ) {
1057       for (keys %$req_bag) {
1058
1059         $_ =~ / \A $modname_re \z /x
1060           or croak "Requirement '$_' in group '$group' is not a valid module name";
1061
1062         # !!!DO NOT CHANGE!!!
1063         # remember - version.pm may not be available on the system
1064         croak "Requirement '$_' in group '$group' specifies an invalid version '$req_bag->{$_}' (only plain non-underscored floating point decimals are supported)"
1065           if ( ($req_bag->{$_}||0) !~ qr/ \A $modver_re \z /x );
1066       }
1067     }
1068
1069     if (my $e = $all_groups->{$group}{missing_envvars}) {
1070       push @{$ret->{missing_envvars}}, @$e;
1071     }
1072
1073     # assemble into the final ret
1074     for my $type (
1075       'modreqs',
1076       ( $ret->{missing_envvars} ? () : 'effective_modreqs' ),
1077     ) {
1078       for my $req_bag ($group_reqs, @{ $augmentations->{$group} || [] } ) {
1079         for my $mod (keys %$req_bag) {
1080
1081           $ret->{$type}{$mod} = $req_bag->{$mod}||0 if (
1082
1083             ! exists $ret->{$type}{$mod}
1084               or
1085             # we sanitized the version to be numeric above - we can just -gt it
1086             ($req_bag->{$mod}||0) > $ret->{$type}{$mod}
1087
1088           );
1089         }
1090       }
1091     }
1092
1093     $ret->{modreqs_fully_documented} &&= !!$dbic_reqs->{$group}{pod}
1094       if $all_groups->{$group}{user_requested};
1095
1096     $ret->{release_testing_mandatory} ||= !!$dbic_reqs->{$group}{release_testing_mandatory};
1097   }
1098
1099   return $ret;
1100 }
1101
1102
1103 # this method tries to find/load specified modreqs and returns a hashref of
1104 # module/loaderror pairs for anything that failed
1105 sub _errorlist_for_modreqs {
1106   # args supposedly already went through _groups_to_reqs and are therefore sanitized
1107   # safe to eval at will
1108   my ($self, $reqs) = @_;
1109
1110   my $ret;
1111
1112   for my $m ( keys %$reqs ) {
1113     my $v = $reqs->{$m};
1114
1115     if (! exists $req_unavailability_cache{$m}{$v} ) {
1116       local $@;
1117       eval( "require $m;" . ( $v ? "$m->VERSION(q($v))" : '' ) );
1118       $req_unavailability_cache{$m}{$v} = $@;
1119     }
1120
1121     $ret->{$m} = $req_unavailability_cache{$m}{$v}
1122       if $req_unavailability_cache{$m}{$v};
1123   }
1124
1125   $ret;
1126 }
1127
1128 # Unlike the above DO NOT try to load anything
1129 # This is executed when some needed envvars are not available
1130 # which in turn means a module load will never be reached anyway
1131 # This is important because some modules (especially DBDs) can be
1132 # *really* fickle when a require() is attempted, with pretty confusing
1133 # side-effects (especially on windows)
1134 sub _list_physically_missing_modules {
1135   my ($self, $modreqs) = @_;
1136
1137   # in case there is a coderef in @INC there is nothing we can definitively prove
1138   # so short circuit directly
1139   return '' if grep { length ref $_ } @INC;
1140
1141   my @definitely_missing;
1142   for my $mod (keys %$modreqs) {
1143     (my $fn = $mod . '.pm') =~ s|::|/|g;
1144
1145     push @definitely_missing, $mod unless grep
1146       # this should work on any combination of slashes
1147       { $_ and -d $_ and -f "$_/$fn" and -r "$_/$fn" }
1148       @INC
1149     ;
1150   }
1151
1152   join ' ', map
1153     { $modreqs->{$_} ? "$_~$modreqs->{$_}" : $_ }
1154     sort { lc($a) cmp lc($b) } @definitely_missing
1155   ;
1156 }
1157
1158
1159 # This is to be called by the author only (automatically in Makefile.PL)
1160 sub _gen_pod {
1161   my ($class, $distver, $pod_dir) = @_;
1162
1163   die "No POD root dir supplied" unless $pod_dir;
1164
1165   $distver ||=
1166     eval { require DBIx::Class; DBIx::Class->VERSION; }
1167       ||
1168     die
1169 "\n\n---------------------------------------------------------------------\n" .
1170 'Unable to load core DBIx::Class module to determine current version, '.
1171 'possibly due to missing dependencies. Author-mode autodocumentation ' .
1172 "halted\n\n" . $@ .
1173 "\n\n---------------------------------------------------------------------\n"
1174   ;
1175
1176   # do not ask for a recent version, use 1.x API calls
1177   # this *may* execute on a smoker with old perl or whatnot
1178   require File::Path;
1179
1180   (my $modfn = __PACKAGE__ . '.pm') =~ s|::|/|g;
1181
1182   (my $podfn = "$pod_dir/$modfn") =~ s/\.pm$/\.pod/;
1183   (my $dir = $podfn) =~ s|/[^/]+$||;
1184
1185   File::Path::mkpath([$dir]);
1186
1187   my $sqltver = $class->req_list_for('deploy')->{'SQL::Translator'}
1188     or die "Hrmm? No sqlt dep?";
1189
1190
1191   my @chunks;
1192
1193 #@@
1194 #@@ HEADER
1195 #@@
1196   push @chunks, <<"EOC";
1197 #########################################################################
1198 #####################  A U T O G E N E R A T E D ########################
1199 #########################################################################
1200 #
1201 # The contents of this POD file are auto-generated.  Any changes you make
1202 # will be lost. If you need to change the generated text edit _gen_pod()
1203 # at the end of $modfn
1204 #
1205
1206 =head1 NAME
1207
1208 $class - Optional module dependency specifications (for module authors)
1209 EOC
1210
1211
1212 #@@
1213 #@@ SYNOPSIS HEADING
1214 #@@
1215   push @chunks, <<"EOC";
1216 =head1 SYNOPSIS
1217
1218 Somewhere in your build-file (e.g. L<ExtUtils::MakeMaker>'s F<Makefile.PL>):
1219
1220   ...
1221
1222   \$EUMM_ARGS{CONFIGURE_REQUIRES} = {
1223     \%{ \$EUMM_ARGS{CONFIGURE_REQUIRES} || {} },
1224     'DBIx::Class' => '$distver',
1225   };
1226
1227   ...
1228
1229   my %DBIC_DEPLOY_AND_ORACLE_DEPS = %{ eval {
1230     require $class;
1231     $class->req_list_for([qw( deploy rdbms_oracle ic_dt )]);
1232   } || {} };
1233
1234   \$EUMM_ARGS{PREREQ_PM} = {
1235     \%DBIC_DEPLOY_AND_ORACLE_DEPS,
1236     \%{ \$EUMM_ARGS{PREREQ_PM} || {} },
1237   };
1238
1239   ...
1240
1241   ExtUtils::MakeMaker::WriteMakefile(\%EUMM_ARGS);
1242
1243 B<Note>: The C<eval> protection within the example is due to support for
1244 requirements during L<the C<configure> build phase|CPAN::Meta::Spec/Phases>
1245 not being available on a sufficient portion of production installations of
1246 Perl. Robust support for such dependency requirements is available in the
1247 L<CPAN> installer only since version C<1.94_56> first made available for
1248 production with perl version C<5.12>. It is the belief of the current
1249 maintainer that support for requirements during the C<configure> build phase
1250 will not be sufficiently ubiquitous until the B<year 2020> at the earliest,
1251 hence the extra care demonstrated above. It should also be noted that some
1252 3rd party installers (e.g. L<cpanminus|App::cpanminus>) do the right thing
1253 with configure requirements independent from the versions of perl and CPAN
1254 available.
1255 EOC
1256
1257
1258 #@@
1259 #@@ DESCRIPTION HEADING
1260 #@@
1261   push @chunks, <<'EOC';
1262 =head1 DESCRIPTION
1263
1264 Some of the less-frequently used features of L<DBIx::Class> have external
1265 module dependencies on their own. In order not to burden the average user
1266 with modules they will never use, these optional dependencies are not included
1267 in the base Makefile.PL. Instead an exception with a descriptive message is
1268 thrown when a specific feature can't find one or several modules required for
1269 its operation. This module is the central holding place for the current list
1270 of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
1271 authors alike.
1272
1273 Dependencies are organized in L<groups|/CURRENT REQUIREMENT GROUPS> where each
1274 group can list one or more required modules, with an optional minimum version
1275 (or 0 for any version). In addition groups prefixed with C<test_> can specify
1276 a set of environment variables, some (or all) of which are marked as required
1277 for the group to be considered by L</req_list_for>
1278
1279 Each group name (or a combination thereof) can be used in the
1280 L<public methods|/METHODS> as described below.
1281 EOC
1282
1283
1284 #@@
1285 #@@ REQUIREMENT GROUPLIST HEADING
1286 #@@
1287   push @chunks, '=head1 CURRENT REQUIREMENT GROUPS';
1288
1289   my $standalone_info;
1290
1291   for my $group (sort keys %$dbic_reqs) {
1292
1293     my $info = $standalone_info->{$group} ||= $class->_groups_to_reqs($group);
1294
1295     next unless (
1296       $info->{modreqs_fully_documented}
1297         and
1298       ( $info->{augments} or $info->{modreqs} )
1299     );
1300
1301     my $p = $dbic_reqs->{$group}{pod};
1302
1303     push @chunks, (
1304       "=head2 $p->{title}",
1305       "=head3 $group",
1306       $p->{desc},
1307       '=over',
1308     );
1309
1310     if ( keys %{ $info->{modreqs}||{} } ) {
1311       push @chunks, map
1312         { "=item * $_" . ($info->{modreqs}{$_} ? " >= $info->{modreqs}{$_}" : '') }
1313         ( sort keys %{ $info->{modreqs} } )
1314       ;
1315     }
1316     else {
1317       push @chunks, '=item * No standalone requirements',
1318     }
1319
1320     push @chunks, '=back';
1321
1322     for my $ag ( sort keys %{ $info->{augments} || {} } ) {
1323       my $ag_info = $standalone_info->{$ag} ||= $class->_groups_to_reqs($ag);
1324
1325       my $newreqs = $class->modreq_list_for([ $group, $ag ]);
1326       for (keys %$newreqs) {
1327         delete $newreqs->{$_} if (
1328           ( defined $info->{modreqs}{$_}    and $info->{modreqs}{$_}    == $newreqs->{$_} )
1329             or
1330           ( defined $ag_info->{modreqs}{$_} and $ag_info->{modreqs}{$_} == $newreqs->{$_} )
1331         );
1332       }
1333
1334       if (keys %$newreqs) {
1335         push @chunks, (
1336           "Combined with L</$ag> additionally requires:",
1337           '=over',
1338           ( map
1339             { "=item * $_" . ($newreqs->{$_} ? " >= $newreqs->{$_}" : '') }
1340             ( sort keys %$newreqs )
1341           ),
1342           '=back',
1343         );
1344       }
1345     }
1346   }
1347
1348
1349 #@@
1350 #@@ API DOCUMENTATION HEADING
1351 #@@
1352   push @chunks, <<'EOC';
1353
1354 =head1 IMPORT-LIKE ACTIONS
1355
1356 Even though this module is not an L<Exporter>, it recognizes several C<actions>
1357 supplied to its C<import> method.
1358
1359 =head2 -skip_all_without
1360
1361 =over
1362
1363 =item Arguments: @group_names
1364
1365 =back
1366
1367 A convenience wrapper for use during testing:
1368 EOC
1369
1370   push @chunks, " use $class -skip_all_without => qw(admin test_rdbms_mysql);";
1371
1372   push @chunks, 'Roughly equivalent to the following code:';
1373
1374   push @chunks, sprintf <<'EOS', ($class) x 2;
1375
1376  BEGIN {
1377    require %s;
1378    if ( my $missing = %s->req_missing_for(\@group_names_) ) {
1379      print "1..0 # SKIP requirements not satisfied: $missing\n";
1380      exit 0;
1381    }
1382  }
1383 EOS
1384
1385   push @chunks, <<'EOC';
1386
1387 It also takes into account the C<RELEASE_TESTING> environment variable and
1388 behaves like L</-die_without> for any requirement groups marked as
1389 C<release_testing_mandatory>.
1390
1391 =head2 -die_without
1392
1393 =over
1394
1395 =item Arguments: @group_names
1396
1397 =back
1398
1399 A convenience wrapper around L</die_unless_req_ok_for>:
1400 EOC
1401
1402   push @chunks, " use $class -die_without => qw(deploy admin);";
1403
1404   push @chunks, <<'EOC';
1405
1406 =head2 -list_missing
1407
1408 =over
1409
1410 =item Arguments: @group_names
1411
1412 =back
1413
1414 A convenience wrapper around L</modreq_missing_for>:
1415
1416  perl -Ilib -MDBIx::Class::Optional::Dependencies=-list_missing,deploy,admin | cpanm
1417
1418 =head1 METHODS
1419
1420 =head2 req_group_list
1421
1422 =over
1423
1424 =item Arguments: none
1425
1426 =item Return Value: \%list_of_requirement_groups
1427
1428 =back
1429
1430 This method should be used by DBIx::Class packagers, to get a hashref of all
1431 dependencies B<keyed> by dependency group. Each key (group name), or a combination
1432 thereof (as an arrayref) can be supplied to the methods below.
1433 The B<values> of the returned hash are currently a set of options B<without a
1434 well defined structure>. If you have use for any of the contents - contact the
1435 maintainers, instead of treating this as public (left alone stable) API.
1436
1437 =head2 req_list_for
1438
1439 =over
1440
1441 =item Arguments: $group_name | \@group_names
1442
1443 =item Return Value: \%set_of_module_version_pairs
1444
1445 =back
1446
1447 This method should be used by DBIx::Class extension authors, to determine the
1448 version of modules a specific set of features requires for this version of
1449 DBIx::Class (regardless of their availability on the system).
1450 See the L</SYNOPSIS> for a real-world example.
1451
1452 When handling C<test_*> groups this method behaves B<differently> from
1453 L</modreq_list_for> below (and is the only such inconsistency among the
1454 C<req_*> methods). If a particular group declares as requirements some
1455 C<environment variables> and these requirements are not satisfied (the envvars
1456 are unset) - then the C<module requirements> of this group are not included in
1457 the returned list.
1458
1459 =head2 modreq_list_for
1460
1461 =over
1462
1463 =item Arguments: $group_name | \@group_names
1464
1465 =item Return Value: \%set_of_module_version_pairs
1466
1467 =back
1468
1469 Same as L</req_list_for> but does not take into consideration any
1470 C<environment variable requirements> - returns just the list of required
1471 modules.
1472
1473 =head2 req_ok_for
1474
1475 =over
1476
1477 =item Arguments: $group_name | \@group_names
1478
1479 =item Return Value: 1|0
1480
1481 =back
1482
1483 Returns true or false depending on whether all modules/envvars required by
1484 the group(s) are loadable/set on the system.
1485
1486 =head2 req_missing_for
1487
1488 =over
1489
1490 =item Arguments: $group_name | \@group_names
1491
1492 =item Return Value: $error_message_string
1493
1494 =back
1495
1496 Returns a single-line string suitable for inclusion in larger error messages.
1497 This method would normally be used by DBIx::Class core features, to indicate to
1498 the user that they need to install specific modules and/or set specific
1499 environment variables before being able to use a specific feature set.
1500
1501 For example if some of the requirements for C<deploy> are not available,
1502 the returned string could look like:
1503 EOC
1504
1505   push @chunks, qq{ "SQL::Translator~$sqltver" (see $class documentation for details)};
1506
1507   push @chunks, <<'EOC';
1508 The author is expected to prepend the necessary text to this message before
1509 returning the actual error seen by the user. See also L</modreq_missing_for>
1510
1511 =head2 modreq_missing_for
1512
1513 =over
1514
1515 =item Arguments: $group_name | \@group_names
1516
1517 =item Return Value: $error_message_string
1518
1519 =back
1520
1521 Same as L</req_missing_for> except that the error string is guaranteed to be
1522 either empty, or contain a set of module requirement specifications suitable
1523 for piping to e.g. L<cpanminus|App::cpanminus>. The method explicitly does not
1524 attempt to validate the state of required environment variables (if any).
1525
1526 For instance if some of the requirements for C<deploy> are not available,
1527 the returned string could look like:
1528 EOC
1529
1530   push @chunks, qq{ "SQL::Translator~$sqltver"};
1531
1532   push @chunks, <<'EOC';
1533
1534 See also L</-list_missing>.
1535
1536 =head2 skip_without
1537
1538 =over
1539
1540 =item Arguments: $group_name | \@group_names
1541
1542 =back
1543
1544 A convenience wrapper around L<skip|Test::More/SKIP>. It does not take neither
1545 a reason (it is generated by L</req_missing_for>) nor an amount of skipped tests
1546 (it is always C<1>, thus mandating unconditional use of
1547 L<done_testing|Test::More/done_testing>). Most useful in combination with ad hoc
1548 requirement specifications:
1549 EOC
1550
1551   push @chunks, <<EOC;
1552   SKIP: {
1553     $class->skip_without([ deploy YAML>=0.90 ]);
1554
1555     ...
1556   }
1557 EOC
1558
1559   push @chunks, <<'EOC';
1560
1561 =head2 die_unless_req_ok_for
1562
1563 =over
1564
1565 =item Arguments: $group_name | \@group_names
1566
1567 =back
1568
1569 Checks if L</req_ok_for> passes for the supplied group(s), and
1570 in case of failure throws an exception including the information
1571 from L</req_missing_for>. See also L</-die_without>.
1572
1573 =head2 modreq_errorlist_for
1574
1575 =over
1576
1577 =item Arguments: $group_name | \@group_names
1578
1579 =item Return Value: \%set_of_loaderrors_per_module
1580
1581 =back
1582
1583 Returns a hashref containing the actual errors that occurred while attempting
1584 to load each module in the requirement group(s).
1585
1586 =head2 req_errorlist_for
1587
1588 Deprecated method name, equivalent (via proxy) to L</modreq_errorlist_for>.
1589
1590 EOC
1591
1592 #@@
1593 #@@ FOOTER
1594 #@@
1595   push @chunks, <<'EOC';
1596 =head1 FURTHER QUESTIONS?
1597
1598 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
1599
1600 =head1 COPYRIGHT AND LICENSE
1601
1602 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
1603 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
1604 redistribute it and/or modify it under the same terms as the
1605 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
1606 EOC
1607
1608   eval {
1609     open (my $fh, '>', $podfn) or die;
1610     print $fh join ("\n\n", @chunks) or die;
1611     print $fh "\n" or die;
1612     close ($fh) or die;
1613   } or croak( "Unable to write $podfn: " . ( $! || $@ || 'unknown error') );
1614 }
1615
1616 1;