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 {
 658   my $self = shift;
 659   $self->_errorlist_for_modreqs( $self->_groups_to_reqs(@_)->{modreqs} );
 660 }
 661
 662 sub req_ok_for {
 663   my $self = shift;
 664   $self->_errorlist_for_modreqs( $self->_groups_to_reqs(@_)->{modreqs} )
 665     ? 0
 666     : 1
 667   ;
 668 }
 669
 670 sub req_missing_for {
 671   my $self = shift;
 672
 673   my $reqs = $self->_groups_to_reqs(@_);
 674   my $modreq_errors = $self->_errorlist_for_modreqs($reqs->{modreqs}) or return '';
 675
 676   join ' ',
 677     (map { $reqs->{modreqs}{$_} ? qq("$_~>=$reqs->{modreqs}{$_}") : $_ } sort keys %$modreq_errors),
 678     ( $reqs->{modreqs_fully_documented} ? "(see @{[ ref $self || $self ]} documentation for details)" : () ),
 679   ;
 680 }
 681
 682 sub die_unless_req_ok_for {
 683   if (my $err = shift->req_missing_for(@_) ) {
 684     die "Required modules missing, unable to continue: $err\n";
 685   }
 686 }
 687
 688
 689
 690 ### Private OO API
 691 our %req_unavailability_cache;
 692
 693 # this method is just a lister/metadata checker - it does not try to load anything
 694 sub _groups_to_reqs {
 695   my ($self, $groups) = @_;
 696
 697   $groups = [ $groups || () ]
 698     unless ref $groups eq 'ARRAY';
 699
 700   croak "@{[ (caller(1))[3] ]}() expects a requirement group name or arrayref of group names"
 701     unless @$groups;
 702
 703   my $ret = {
 704     modreqs => {},
 705     modreqs_fully_documented => 1,
 706   };
 707
 708
 709   for my $group ( @$groups ) {
 710
 711     $group =~ /\A [A-Za-z][0-9A-Z_a-z]* \z/x
 712       or croak "Invalid requirement group name '$group': only ascii alphanumerics and _ are allowed";
 713
 714     my $group_reqs = ($dbic_reqs->{$group}||{})->{req}
 715       or croak "Requirement group '$group' is not defined";
 716
 717     # sanity-check
 718     for (keys %$group_reqs) {
 719
 720       $_ =~ /\A [A-Z_a-z][0-9A-Z_a-z]* (?:::[0-9A-Z_a-z]+)* \z /x
 721         or croak "Requirement '$_' in group '$group' is not a valid module name";
 722
 723       # !!!DO NOT CHANGE!!!
 724       # remember - version.pm may not be available on the system
 725       croak "Requirement '$_' in group '$group' specifies an invalid version '$group_reqs->{$_}' (only plain non-underscored floating point decimals are supported)"
 726         if ( ($group_reqs->{$_}||0) !~ / \A [0-9]+ (?: \. [0-9]+ )? \z /x );
 727     }
 728
 729     # assemble into the final ret
 730     for (keys %$group_reqs) {
 731
 732       $ret->{modreqs}{$_} = $group_reqs->{$_}||0 if (
 733
 734         ! exists $ret->{modreqs}{$_}
 735           or
 736         # we sanitized the version to be numeric above - we can just -gt it
 737         ($group_reqs->{$_}||0) > $ret->{modreqs}{$_}
 738
 739       );
 740     }
 741
 742     $ret->{modreqs_fully_documented} &&= !!$dbic_reqs->{$group}{pod};
 743   }
 744
 745   return $ret;
 746 }
 747
 748
 749 # this method tries to load specified modreqs and returns a hashref of
 750 # module/loaderror pairs for anything that failed
 751 sub _errorlist_for_modreqs {
 752   # args supposedly already went through _groups_to_reqs and are therefore sanitized
 753   # safe to eval at will
 754   my ($self, $reqs) = @_;
 755
 756   my $ret;
 757
 758   for my $m ( keys %$reqs ) {
 759     my $v = $reqs->{$m};
 760
 761     if (! exists $req_unavailability_cache{$m}{$v} ) {
 762       local $@;
 763       eval( "require $m;" . ( $v ? "$m->VERSION(q($v))" : '' ) );
 764       $req_unavailability_cache{$m}{$v} = $@;
 765     }
 766
 767     $ret->{$m} = $req_unavailability_cache{$m}{$v}
 768       if $req_unavailability_cache{$m}{$v};
 769   }
 770
 771   $ret;
 772 }
 773
 774
 775 # This is to be called by the author only (automatically in Makefile.PL)
 776 sub _gen_pod {
 777   my ($class, $distver, $pod_dir) = @_;
 778
 779   die "No POD root dir supplied" unless $pod_dir;
 780
 781   $distver ||=
 782     eval { require DBIx::Class; DBIx::Class->VERSION; }
 783       ||
 784     die
 785 "\n\n---------------------------------------------------------------------\n" .
 786 'Unable to load core DBIx::Class module to determine current version, '.
 787 'possibly due to missing dependencies. Author-mode autodocumentation ' .
 788 "halted\n\n" . $@ .
 789 "\n\n---------------------------------------------------------------------\n"
 790   ;
 791
 792   # do not ask for a recent version, use 1.x API calls
 793   # this *may* execute on a smoker with old perl or whatnot
 794   require File::Path;
 795
 796   (my $modfn = __PACKAGE__ . '.pm') =~ s|::|/|g;
 797
 798   (my $podfn = "$pod_dir/$modfn") =~ s/\.pm$/\.pod/;
 799   (my $dir = $podfn) =~ s|/[^/]+$||;
 800
 801   File::Path::mkpath([$dir]);
 802
 803   my $sqltver = $class->req_list_for('deploy')->{'SQL::Translator'}
 804     or die "Hrmm? No sqlt dep?";
 805
 806
 807   my @chunks;
 808
 809 #@@
 810 #@@ HEADER
 811 #@@
 812   push @chunks, <<"EOC";
 813 #########################################################################
 814 #####################  A U T O G E N E R A T E D ########################
 815 #########################################################################
 816 #
 817 # The contents of this POD file are auto-generated.  Any changes you make
 818 # will be lost. If you need to change the generated text edit _gen_pod()
 819 # at the end of $modfn
 820 #
 821
 822 =head1 NAME
 823
 824 $class - Optional module dependency specifications (for module authors)
 825 EOC
 826
 827
 828 #@@
 829 #@@ SYNOPSIS HEADING
 830 #@@
 831   push @chunks, <<"EOC";
 832 =head1 SYNOPSIS
 833
 834 Somewhere in your build-file (e.g. L<ExtUtils::MakeMaker>'s F<Makefile.PL>):
 835
 836   ...
 837
 838   \$EUMM_ARGS{CONFIGURE_REQUIRES} = {
 839     \%{ \$EUMM_ARGS{CONFIGURE_REQUIRES} || {} },
 840     'DBIx::Class' => '$distver',
 841   };
 842
 843   ...
 844
 845   my %DBIC_DEPLOY_DEPS = %{ eval {
 846     require $class;
 847     $class->req_list_for('deploy');
 848   } || {} };
 849
 850   \$EUMM_ARGS{PREREQ_PM} = {
 851     \%DBIC_DEPLOY_DEPS,
 852     \%{ \$EUMM_ARGS{PREREQ_PM} || {} },
 853   };
 854
 855   ...
 856
 857   ExtUtils::MakeMaker::WriteMakefile(\%EUMM_ARGS);
 858
 859 B<Note>: The C<eval> protection within the example is due to support for
 860 requirements during L<the C<configure> build phase|CPAN::Meta::Spec/Phases>
 861 not being available on a sufficient portion of production installations of
 862 Perl. Robust support for such dependency requirements is available in the
 863 L<CPAN> installer only since version C<1.94_56> first made available for
 864 production with perl version C<5.12>. It is the belief of the current
 865 maintainer that support for requirements during the C<configure> build phase
 866 will not be sufficiently ubiquitous until the B<year 2020> at the earliest,
 867 hence the extra care demonstrated above. It should also be noted that some
 868 3rd party installers (e.g. L<cpanminus|App::cpanminus>) do the right thing
 869 with configure requirements independent from the versions of perl and CPAN
 870 available.
 871 EOC
 872
 873
 874 #@@
 875 #@@ DESCRIPTION HEADING
 876 #@@
 877   push @chunks, <<'EOC';
 878 =head1 DESCRIPTION
 879
 880 Some of the less-frequently used features of L<DBIx::Class> have external
 881 module dependencies on their own. In order not to burden the average user
 882 with modules they will never use, these optional dependencies are not included
 883 in the base Makefile.PL. Instead an exception with a descriptive message is
 884 thrown when a specific feature can't find one or several modules required for
 885 its operation. This module is the central holding place for the current list
 886 of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
 887 authors alike.
 888
 889 Dependencies are organized in L<groups|/CURRENT REQUIREMENT GROUPS> where each
 890 group can list one or more required modules, with an optional minimum version
 891 (or 0 for any version). Each group name (or a combination thereof) can be used
 892 in the L<public methods|/METHODS> as described below.
 893 EOC
 894
 895
 896 #@@
 897 #@@ REQUIREMENT GROUPLIST HEADING
 898 #@@
 899   push @chunks, '=head1 CURRENT REQUIREMENT GROUPS';
 900
 901   for my $group (sort keys %$dbic_reqs) {
 902     my $p = $dbic_reqs->{$group}{pod}
 903       or next;
 904
 905     my $modlist = $dbic_reqs->{$group}{req}
 906       or next;
 907
 908     next unless keys %$modlist;
 909
 910     push @chunks, (
 911       "=head2 $p->{title}",
 912       "$p->{desc}",
 913       '=over',
 914       ( map { "=item * $_" . ($modlist->{$_} ? " >= $modlist->{$_}" : '') } (sort keys %$modlist) ),
 915       '=back',
 916       "Requirement group: B<$group>",
 917     );
 918   }
 919
 920
 921 #@@
 922 #@@ API DOCUMENTATION HEADING
 923 #@@
 924   push @chunks, <<'EOC';
 925
 926 =head1 METHODS
 927
 928 =head2 req_group_list
 929
 930 =over
 931
 932 =item Arguments: none
 933
 934 =item Return Value: \%list_of_requirement_groups
 935
 936 =back
 937
 938 This method should be used by DBIx::Class packagers, to get a hashref of all
 939 dependencies B<keyed> by dependency group. Each key (group name), or a combination
 940 thereof (as an arrayref) can be supplied to the methods below.
 941 The B<values> of the returned hash are currently a set of options B<without a
 942 well defined structure>. If you have use for any of the contents - contact the
 943 maintainers, instead of treating this as public (left alone stable) API.
 944
 945 =head2 req_list_for
 946
 947 =over
 948
 949 =item Arguments: $group_name | \@group_names
 950
 951 =item Return Value: \%set_of_module_version_pairs
 952
 953 =back
 954
 955 This method should be used by DBIx::Class extension authors, to determine the
 956 version of modules a specific set of features requires for this version of
 957 DBIx::Class. See the L</SYNOPSIS> for a real-world example.
 958
 959 =head2 req_ok_for
 960
 961 =over
 962
 963 =item Arguments: $group_name | \@group_names
 964
 965 =item Return Value: 1|0
 966
 967 =back
 968
 969 Returns true or false depending on whether all modules required by
 970 the group(s) are present on the system and loadable.
 971
 972 =head2 req_missing_for
 973
 974 =over
 975
 976 =item Arguments: $group_name | \@group_names
 977
 978 =item Return Value: $error_message_string
 979
 980 =back
 981
 982 Returns a single-line string suitable for inclusion in larger error messages.
 983 This method would normally be used by DBIx::Class core-modules, to indicate to
 984 the user that they need to install specific modules before being able to use a
 985 specific feature set.
 986
 987 For example if some of the requirements for C<deploy> are not available,
 988 the returned string could look like:
 989 EOC
 990
 991   push @chunks, qq{ "SQL::Translator~>=$sqltver" (see $class documentation for details)};
 992
 993   push @chunks, <<'EOC';
 994 The author is expected to prepend the necessary text to this message before
 995 returning the actual error seen by the user.
 996
 997 =head2 die_unless_req_ok_for
 998
 999 =over
1000
1001 =item Arguments: $group_name | \@group_names
1002
1003 =back
1004
1005 Checks if L</req_ok_for> passes for the supplied group(s), and
1006 in case of failure throws an exception including the information
1007 from L</req_missing_for>.
1008
1009 =head2 req_errorlist_for
1010
1011 =over
1012
1013 =item Arguments: $group_name | \@group_names
1014
1015 =item Return Value: \%set_of_loaderrors_per_module
1016
1017 =back
1018
1019 Returns a hashref containing the actual errors that occurred while attempting
1020 to load each module in the requirement group(s).
1021 EOC
1022
1023
1024 #@@
1025 #@@ FOOTER
1026 #@@
1027   push @chunks, <<'EOC';
1028 =head1 FURTHER QUESTIONS?
1029
1030 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
1031
1032 =head1 COPYRIGHT AND LICENSE
1033
1034 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
1035 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
1036 redistribute it and/or modify it under the same terms as the
1037 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
1038 EOC
1039
1040   eval {
1041     open (my $fh, '>', $podfn) or die;
1042     print $fh join ("\n\n", @chunks) or die;
1043     print $fh "\n" or die;
1044     close ($fh) or die;
1045   } or croak( "Unable to write $podfn: " . ( $! || $@ || 'unknown error') );
1046 }
1047
1048 1;