lib/DBIx/Class/Optional/Dependencies.pm

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