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