Make OptDeps aware of envvars as first-class requirements (test_* groups only)
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Optional / Dependencies.pm
CommitLineData
8057ed01 1package DBIx::Class::Optional::Dependencies;
2
3use warnings;
4use strict;
5
3f5e367a 6use Carp;
fb39747c 7
8# NO EXTERNAL NON-5.8.1 CORE DEPENDENCIES EVER (e.g. C::A::G)
8057ed01 9# This module is to be loaded by Makefile.PM on a pristine system
10
f6b26571 11# POD is generated automatically by calling _gen_pod from the
12# Makefile.PL in $AUTHOR mode
13
3ade80ee 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
17my $min_json_any = {
be855469 18 'JSON::Any' => '1.23',
2a2a7b23 19};
3ade80ee 20my $test_and_dist_json_any = {
21 'JSON::Any' => '1.31',
22};
2a2a7b23 23
2b48ebff 24my $moose_basic = {
68de9438 25 'Moose' => '0.98',
26 'MooseX::Types' => '0.21',
d401ab6b 27 'MooseX::Types::LoadableClass' => '0.011',
68de9438 28};
29
30my $replicated = {
31 %$moose_basic,
2b48ebff 32};
33
ebcd0e4f 34my $admin_basic = {
35 %$moose_basic,
3ade80ee 36 %$min_json_any,
68de9438 37 'MooseX::Types::Path::Class' => '0.05',
38 'MooseX::Types::JSON' => '0.02',
68de9438 39};
40
a0361822 41my $admin_script = {
42 %$moose_basic,
43 %$admin_basic,
44 'Getopt::Long::Descriptive' => '0.081',
45 'Text::CSV' => '1.16',
46};
47
68de9438 48my $datetime_basic = {
49 'DateTime' => '0.55',
50 'DateTime::Format::Strptime' => '1.2',
ebcd0e4f 51};
52
c7d50a7d 53my $id_shortener = {
26022fb5 54 'Math::BigInt' => '1.80',
c7d50a7d 55 'Math::Base36' => '0.07',
56};
57
be68095d 58my $rdbms_sqlite = {
59 'DBD::SQLite' => '0',
60};
61my $rdbms_pg = {
62 'DBD::Pg' => '0',
63};
64my $rdbms_mssql_odbc = {
65 'DBD::ODBC' => '0',
66};
67my $rdbms_mssql_sybase = {
68 'DBD::Sybase' => '0',
69};
56dca25f 70my $rdbms_mssql_ado = {
71 'DBD::ADO' => '0',
72};
726c8f65 73my $rdbms_msaccess_odbc = {
74 'DBD::ODBC' => '0',
75};
76my $rdbms_msaccess_ado = {
77 'DBD::ADO' => '0',
78};
be68095d 79my $rdbms_mysql = {
80 'DBD::mysql' => '0',
81};
82my $rdbms_oracle = {
83 'DBD::Oracle' => '0',
84 %$id_shortener,
85};
86my $rdbms_ase = {
87 'DBD::Sybase' => '0',
88};
89my $rdbms_db2 = {
90 'DBD::DB2' => '0',
91};
199fbc45 92my $rdbms_db2_400 = {
93 'DBD::ODBC' => '0',
94};
95my $rdbms_informix = {
96 'DBD::Informix' => '0',
97};
98my $rdbms_sqlanywhere = {
99 'DBD::SQLAnywhere' => '0',
100};
101my $rdbms_sqlanywhere_odbc = {
102 'DBD::ODBC' => '0',
103};
104my $rdbms_firebird = {
105 'DBD::Firebird' => '0',
106};
107my $rdbms_firebird_interbase = {
108 'DBD::InterBase' => '0',
109};
e02b39b4 110my $rdbms_firebird_odbc = {
111 'DBD::ODBC' => '0',
112};
be68095d 113
31c31b8d 114my $dbic_reqs = {
8057ed01 115 replicated => {
68de9438 116 req => $replicated,
f6b26571 117 pod => {
118 title => 'Storage::Replicated',
119 desc => 'Modules required for L<DBIx::Class::Storage::DBI::Replicated>',
120 },
8057ed01 121 },
122
68de9438 123 test_replicated => {
124 req => {
125 %$replicated,
126 'Test::Moose' => '0',
127 },
128 },
129
130
8057ed01 131 admin => {
2b48ebff 132 req => {
ebcd0e4f 133 %$admin_basic,
134 },
135 pod => {
136 title => 'DBIx::Class::Admin',
137 desc => 'Modules required for the DBIx::Class administrative library',
138 },
139 },
140
a4a02f15 141 admin_script => {
ebcd0e4f 142 req => {
a0361822 143 %$admin_script,
2b48ebff 144 },
e144415f 145 pod => {
146 title => 'dbicadmin',
147 desc => 'Modules required for the CLI DBIx::Class interface dbicadmin',
148 },
8057ed01 149 },
150
151 deploy => {
f6b26571 152 req => {
08ac7648 153 'SQL::Translator' => '0.11018',
f6b26571 154 },
155 pod => {
156 title => 'Storage::DBI::deploy()',
5529838f 157 desc => 'Modules required for L<DBIx::Class::Storage::DBI/deployment_statements> and L<DBIx::Class::Schema/deploy>',
f6b26571 158 },
8057ed01 159 },
160
c7d50a7d 161 id_shortener => {
162 req => $id_shortener,
163 },
164
0d374214 165 test_component_accessor => {
166 req => {
167 'Class::Unload' => '0.07',
168 },
169 },
170
a109c954 171 test_pod => {
f6b26571 172 req => {
cbb19edf 173 'Test::Pod' => '1.42',
a109c954 174 },
175 },
176
177 test_podcoverage => {
178 req => {
f6b26571 179 'Test::Pod::Coverage' => '1.08',
180 'Pod::Coverage' => '0.20',
a109c954 181 },
182 },
183
ffce4b65 184 test_whitespace => {
a109c954 185 req => {
8273e845 186 'Test::EOL' => '1.0',
ffce4b65 187 'Test::NoTabs' => '0.9',
f6b26571 188 },
8057ed01 189 },
190
4a233f30 191 test_strictures => {
192 req => {
b2c1212f 193 'Test::Strict' => '0.20',
4a233f30 194 },
195 },
196
2a2a7b23 197 test_prettydebug => {
3ade80ee 198 req => $min_json_any,
2a2a7b23 199 },
200
99503754 201 test_admin_script => {
202 req => {
203 %$admin_script,
3ade80ee 204 %$test_and_dist_json_any,
99503754 205 'JSON' => 0,
be855469 206 'JSON::PP' => 0,
207 'Cpanel::JSON::XS' => 0,
99503754 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
556c4fe6 218 test_leaks_heavy => {
f6b26571 219 req => {
556c4fe6 220 'Class::MethodCache' => '0.02',
221 'PadWalker' => '1.06',
a109c954 222 },
223 },
f6b26571 224
68de9438 225 test_dt => {
226 req => $datetime_basic,
227 },
228
229 test_dt_sqlite => {
a109c954 230 req => {
68de9438 231 %$datetime_basic,
f6b26571 232 # t/36datetime.t
233 # t/60core.t
234 'DateTime::Format::SQLite' => '0',
68de9438 235 },
236 },
f6b26571 237
68de9438 238 test_dt_mysql => {
239 req => {
240 %$datetime_basic,
9c92bb1c 241 # t/inflate/datetime_mysql.t
242 # (doesn't need Mysql itself)
68de9438 243 'DateTime::Format::MySQL' => '0',
244 },
245 },
9c92bb1c 246
68de9438 247 test_dt_pg => {
248 req => {
249 %$datetime_basic,
9c92bb1c 250 # t/inflate/datetime_pg.t
251 # (doesn't need PG itself)
ab35aeab 252 'DateTime::Format::Pg' => '0.16004',
f6b26571 253 },
8057ed01 254 },
255
68de9438 256 test_cdbicompat => {
f6b26571 257 req => {
f6b26571 258 'Class::DBI::Plugin::DeepAbstractSearch' => '0',
d9bd5195 259 %$datetime_basic,
f6b26571 260 'Time::Piece::MySQL' => '0',
f6b26571 261 'Date::Simple' => '3.03',
262 },
8057ed01 263 },
264
be68095d 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 => {
a4fc1239 279 # when changing this list make sure to adjust xt/optional_deps.t
be68095d 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',
56dca25f 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',
be68095d 315 },
316 },
317
726c8f65 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
be68095d 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
199fbc45 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 },
8273e845 396 },
199fbc45 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 },
8273e845 406 },
199fbc45 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 },
8273e845 416 },
199fbc45 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 },
8273e845 426 },
199fbc45 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 },
8273e845 436 },
199fbc45 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 },
8273e845 446 },
199fbc45 447
68de9438 448 test_rdbms_pg => {
e3a7746c 449 env => [
450 DBICTEST_PG_DSN => 1,
451 DBICTEST_PG_USER => 0,
452 DBICTEST_PG_PASS => 0,
453 ],
f6b26571 454 req => {
e3a7746c 455 # the order does matter because the rdbms support group might require
456 # a different version that the test group
457 #
458 # when changing this list make sure to adjust xt/optional_deps.t
459 %$rdbms_pg,
460 'DBD::Pg' => '2.009002', # specific version to test bytea
f6b26571 461 },
8057ed01 462 },
463
afae8507 464 test_rdbms_mssql_odbc => {
e3a7746c 465 env => [
466 DBICTEST_MSSQL_ODBC_DSN => 1,
467 DBICTEST_MSSQL_ODBC_USER => 0,
468 DBICTEST_MSSQL_ODBC_PASS => 0,
469 ],
afae8507 470 req => {
e3a7746c 471 %$rdbms_mssql_odbc,
afae8507 472 },
473 },
474
56dca25f 475 test_rdbms_mssql_ado => {
e3a7746c 476 env => [
477 DBICTEST_MSSQL_ADO_DSN => 1,
478 DBICTEST_MSSQL_ADO_USER => 0,
479 DBICTEST_MSSQL_ADO_PASS => 0,
480 ],
56dca25f 481 req => {
e3a7746c 482 %$rdbms_mssql_ado,
56dca25f 483 },
484 },
485
afae8507 486 test_rdbms_mssql_sybase => {
e3a7746c 487 env => [
488 DBICTEST_MSSQL_DSN => 1,
489 DBICTEST_MSSQL_USER => 0,
490 DBICTEST_MSSQL_PASS => 0,
491 ],
afae8507 492 req => {
e3a7746c 493 %$rdbms_mssql_sybase,
afae8507 494 },
495 },
496
726c8f65 497 test_rdbms_msaccess_odbc => {
e3a7746c 498 env => [
499 DBICTEST_MSACCESS_ODBC_DSN => 1,
500 DBICTEST_MSACCESS_ODBC_USER => 0,
501 DBICTEST_MSACCESS_ODBC_PASS => 0,
502 ],
726c8f65 503 req => {
e3a7746c 504 %$rdbms_msaccess_odbc,
505 %$datetime_basic,
506 'Data::GUID' => '0',
726c8f65 507 },
508 },
509
510 test_rdbms_msaccess_ado => {
e3a7746c 511 env => [
512 DBICTEST_MSACCESS_ADO_DSN => 1,
513 DBICTEST_MSACCESS_ADO_USER => 0,
514 DBICTEST_MSACCESS_ADO_PASS => 0,
515 ],
726c8f65 516 req => {
e3a7746c 517 %$rdbms_msaccess_ado,
518 %$datetime_basic,
519 'Data::GUID' => 0,
726c8f65 520 },
521 },
522
68de9438 523 test_rdbms_mysql => {
e3a7746c 524 env => [
525 DBICTEST_MYSQL_DSN => 1,
526 DBICTEST_MYSQL_USER => 0,
527 DBICTEST_MYSQL_PASS => 0,
528 ],
f6b26571 529 req => {
e3a7746c 530 %$rdbms_mysql,
f6b26571 531 },
8057ed01 532 },
533
68de9438 534 test_rdbms_oracle => {
e3a7746c 535 env => [
536 DBICTEST_ORA_DSN => 1,
537 DBICTEST_ORA_USER => 0,
538 DBICTEST_ORA_PASS => 0,
539 ],
f6b26571 540 req => {
e3a7746c 541 %$rdbms_oracle,
542 'DateTime::Format::Oracle' => '0',
543 'DBD::Oracle' => '1.24',
f6b26571 544 },
8057ed01 545 },
546
68de9438 547 test_rdbms_ase => {
e3a7746c 548 env => [
549 DBICTEST_SYBASE_DSN => 1,
550 DBICTEST_SYBASE_USER => 0,
551 DBICTEST_SYBASE_PASS => 0,
552 ],
f6b26571 553 req => {
e3a7746c 554 %$rdbms_ase,
f6b26571 555 },
8057ed01 556 },
557
68de9438 558 test_rdbms_db2 => {
e3a7746c 559 env => [
560 DBICTEST_DB2_DSN => 1,
561 DBICTEST_DB2_USER => 0,
562 DBICTEST_DB2_PASS => 0,
563 ],
f58a165c 564 req => {
e3a7746c 565 %$rdbms_db2,
f58a165c 566 },
567 },
568
199fbc45 569 test_rdbms_db2_400 => {
e3a7746c 570 env => [
571 DBICTEST_DB2_400_DSN => 1,
572 DBICTEST_DB2_400_USER => 0,
573 DBICTEST_DB2_400_PASS => 0,
574 ],
199fbc45 575 req => {
e3a7746c 576 %$rdbms_db2_400,
199fbc45 577 },
578 },
579
580 test_rdbms_informix => {
e3a7746c 581 env => [
582 DBICTEST_INFORMIX_DSN => 1,
583 DBICTEST_INFORMIX_USER => 0,
584 DBICTEST_INFORMIX_PASS => 0,
585 ],
199fbc45 586 req => {
e3a7746c 587 %$rdbms_informix,
199fbc45 588 },
589 },
590
591 test_rdbms_sqlanywhere => {
e3a7746c 592 env => [
593 DBICTEST_SQLANYWHERE_DSN => 1,
594 DBICTEST_SQLANYWHERE_USER => 0,
595 DBICTEST_SQLANYWHERE_PASS => 0,
596 ],
199fbc45 597 req => {
e3a7746c 598 %$rdbms_sqlanywhere,
199fbc45 599 },
600 },
601
602 test_rdbms_sqlanywhere_odbc => {
e3a7746c 603 env => [
604 DBICTEST_SQLANYWHERE_ODBC_DSN => 1,
605 DBICTEST_SQLANYWHERE_ODBC_USER => 0,
606 DBICTEST_SQLANYWHERE_ODBC_PASS => 0,
607 ],
199fbc45 608 req => {
e3a7746c 609 %$rdbms_sqlanywhere_odbc,
199fbc45 610 },
611 },
612
613 test_rdbms_firebird => {
e3a7746c 614 env => [
615 DBICTEST_FIREBIRD_DSN => 1,
616 DBICTEST_FIREBIRD_USER => 0,
617 DBICTEST_FIREBIRD_PASS => 0,
618 ],
199fbc45 619 req => {
e3a7746c 620 %$rdbms_firebird,
199fbc45 621 },
622 },
623
624 test_rdbms_firebird_interbase => {
e3a7746c 625 env => [
626 DBICTEST_FIREBIRD_INTERBASE_DSN => 1,
627 DBICTEST_FIREBIRD_INTERBASE_USER => 0,
628 DBICTEST_FIREBIRD_INTERBASE_PASS => 0,
629 ],
199fbc45 630 req => {
e3a7746c 631 %$rdbms_firebird_interbase,
199fbc45 632 },
633 },
634
e02b39b4 635 test_rdbms_firebird_odbc => {
e3a7746c 636 env => [
637 DBICTEST_FIREBIRD_ODBC_DSN => 1,
638 DBICTEST_FIREBIRD_ODBC_USER => 0,
639 DBICTEST_FIREBIRD_ODBC_PASS => 0,
640 ],
e02b39b4 641 req => {
e3a7746c 642 %$rdbms_firebird_odbc,
e02b39b4 643 },
644 },
645
42168332 646 test_memcached => {
e3a7746c 647 env => [
648 DBICTEST_MEMCACHED => 1,
649 ],
42168332 650 req => {
e3a7746c 651 'Cache::Memcached' => 0,
42168332 652 },
653 },
654
344f1f52 655 dist_dir => {
656 req => {
3ade80ee 657 %$test_and_dist_json_any,
b81d8515 658 'ExtUtils::MakeMaker' => '6.64',
06fc872a 659 'Pod::Inherit' => '0.91',
660 },
344f1f52 661 },
662
663 dist_upload => {
664 req => {
665 'CPAN::Uploader' => '0.103001',
666 },
667 },
668
8057ed01 669};
670
f6b26571 671
3ca0dcf0 672
673### Public API
674
675# OO for (mistakenly considered) ease of extensibility, not due to any need to
676# carry state of any sort. This API is currently used outside, so leave as-is.
677# FIXME - make sure to not propagate this further if module is extracted as a
678# standalone library - keep the stupidity to a DBIC-secific shim!
679#
fb39747c 680sub req_list_for {
e3a7746c 681 shift->_groups_to_reqs(@_)->{effective_modreqs};
682}
683
684sub modreq_list_for {
31c31b8d 685 shift->_groups_to_reqs(@_)->{modreqs};
fb39747c 686}
687
3ca0dcf0 688sub req_group_list {
31c31b8d 689 +{ map
690 { $_ => $_[0]->_groups_to_reqs($_) }
691 keys %$dbic_reqs
692 }
3ca0dcf0 693}
fb39747c 694
5ffa39c7 695sub req_errorlist_for { shift->modreq_errorlist_for(@_) } # deprecated
696sub modreq_errorlist_for {
31c31b8d 697 my $self = shift;
698 $self->_errorlist_for_modreqs( $self->_groups_to_reqs(@_)->{modreqs} );
344f1f52 699}
700
fb39747c 701sub req_ok_for {
e3a7746c 702 shift->req_missing_for(@_) ? 0 : 1;
703}
704
705sub req_missing_for {
31c31b8d 706 my $self = shift;
e3a7746c 707
708 my $reqs = $self->_groups_to_reqs(@_);
709 my $mods_missing = $self->modreq_missing_for(@_);
710
711 return '' if
712 ! $mods_missing
713 and
714 ! $reqs->{missing_envvars}
31c31b8d 715 ;
e3a7746c 716
717 my @res = $mods_missing || ();
718
719 push @res, 'the following group(s) of environment variables: ' . join ' and ', map
720 { __envvar_group_desc($_) }
721 @{$reqs->{missing_envvars}}
722 if $reqs->{missing_envvars};
723
724 return (
725 ( join ' as well as ', @res )
726 .
727 ( $reqs->{modreqs_fully_documented} ? " (see @{[ ref $self || $self ]} documentation for details)" : '' ),
728 );
fb39747c 729}
730
e3a7746c 731sub modreq_missing_for {
31c31b8d 732 my $self = shift;
fb39747c 733
31c31b8d 734 my $reqs = $self->_groups_to_reqs(@_);
e3a7746c 735 my $modreq_errors = $self->_errorlist_for_modreqs($reqs->{modreqs})
736 or return '';
fb39747c 737
e3a7746c 738 join ' ', map
739 { $reqs->{modreqs}{$_} ? qq("$_~>=$reqs->{modreqs}{$_}") : $_ }
740 sort { lc($a) cmp lc($b) } keys %$modreq_errors
31c31b8d 741 ;
fb39747c 742}
743
3ca0dcf0 744sub die_unless_req_ok_for {
31c31b8d 745 if (my $err = shift->req_missing_for(@_) ) {
e3a7746c 746 die "Unable to continue due to missing requirements: $err\n";
31c31b8d 747 }
fb39747c 748}
749
3ca0dcf0 750
751
e3a7746c 752### Private functions
753
754# potentially shorten group desc
755sub __envvar_group_desc {
756 my @envs = @{$_[0]};
757
758 my (@res, $last_prefix);
759 while (my $ev = shift @envs) {
760 my ($pref, $sep, $suff) = split / ([\_\-]) (?= [^\_\-]+ \z )/x, $ev;
761
762 if ( defined $sep and ($last_prefix||'') eq $pref ) {
763 push @res, "...${sep}${suff}"
764 }
765 else {
766 push @res, $ev;
767 }
768
769 $last_prefix = $pref if $sep;
770 }
771
772 join '/', @res;
773}
774
775
776
79b1bf0a 777### Private OO API
31c31b8d 778our %req_unavailability_cache;
779
e3a7746c 780# this method is just a lister and envvar/metadata checker - it does not try to load anything
31c31b8d 781sub _groups_to_reqs {
782 my ($self, $groups) = @_;
783
784 $groups = [ $groups || () ]
785 unless ref $groups eq 'ARRAY';
786
787 croak "@{[ (caller(1))[3] ]}() expects a requirement group name or arrayref of group names"
788 unless @$groups;
789
790 my $ret = {
791 modreqs => {},
792 modreqs_fully_documented => 1,
793 };
3ca0dcf0 794
31c31b8d 795 for my $group ( @$groups ) {
d8799bab 796
31c31b8d 797 $group =~ /\A [A-Za-z][0-9A-Z_a-z]* \z/x
798 or croak "Invalid requirement group name '$group': only ascii alphanumerics and _ are allowed";
d8799bab 799
31c31b8d 800 my $group_reqs = ($dbic_reqs->{$group}||{})->{req}
801 or croak "Requirement group '$group' is not defined";
d8799bab 802
31c31b8d 803 # sanity-check
804 for (keys %$group_reqs) {
d8799bab 805
31c31b8d 806 $_ =~ /\A [A-Z_a-z][0-9A-Z_a-z]* (?:::[0-9A-Z_a-z]+)* \z /x
807 or croak "Requirement '$_' in group '$group' is not a valid module name";
808
809 # !!!DO NOT CHANGE!!!
810 # remember - version.pm may not be available on the system
811 croak "Requirement '$_' in group '$group' specifies an invalid version '$group_reqs->{$_}' (only plain non-underscored floating point decimals are supported)"
812 if ( ($group_reqs->{$_}||0) !~ / \A [0-9]+ (?: \. [0-9]+ )? \z /x );
d8799bab 813 }
814
e3a7746c 815 # check if we have all required envvars if such names are defined
816 my ($some_envs_required, $some_envs_missing);
817 if (my @e = @{$dbic_reqs->{$group}{env} || [] }) {
818
819 croak "Unexpected 'env' attribute under group '$group' (only allowed in test_* groups)"
820 unless $group =~ /^test_/;
821
822 croak "Unexpected *odd* list in 'env' under group '$group'"
823 if @e % 2;
824
825 my @group_envnames_list;
826
827 # deconstruct the whole thing
828 while (@e) {
829 push @group_envnames_list, my $envname = shift @e;
830
831 # env required or not
832 next unless shift @e;
833
834 $some_envs_required ||= 1;
835
836 $some_envs_missing ||= (
837 ! defined $ENV{$envname}
838 or
839 ! length $ENV{$envname}
840 );
841 }
842
843 croak "None of the envvars in group '$group' declared as required, making the requirement moot"
844 unless $some_envs_required;
845
846 push @{$ret->{missing_envvars}}, \@group_envnames_list if $some_envs_missing;
847 }
848
31c31b8d 849 # assemble into the final ret
e3a7746c 850 for my $type (
851 'modreqs',
852 $some_envs_missing ? () : 'effective_modreqs'
853 ) {
854 for my $mod (keys %$group_reqs) {
31c31b8d 855
e3a7746c 856 $ret->{$type}{$mod} = $group_reqs->{$mod}||0 if (
31c31b8d 857
e3a7746c 858 ! exists $ret->{$type}{$mod}
859 or
860 # we sanitized the version to be numeric above - we can just -gt it
861 ($group_reqs->{$mod}||0) > $ret->{$type}{$mod}
fb39747c 862
e3a7746c 863 );
864 }
fb39747c 865 }
31c31b8d 866
867 $ret->{modreqs_fully_documented} &&= !!$dbic_reqs->{$group}{pod};
868 }
869
870 return $ret;
871}
872
873
874# this method tries to load specified modreqs and returns a hashref of
875# module/loaderror pairs for anything that failed
876sub _errorlist_for_modreqs {
877 # args supposedly already went through _groups_to_reqs and are therefore sanitized
878 # safe to eval at will
879 my ($self, $reqs) = @_;
880
881 my $ret;
882
883 for my $m ( keys %$reqs ) {
884 my $v = $reqs->{$m};
885
886 if (! exists $req_unavailability_cache{$m}{$v} ) {
887 local $@;
888 eval( "require $m;" . ( $v ? "$m->VERSION(q($v))" : '' ) );
889 $req_unavailability_cache{$m}{$v} = $@;
fb39747c 890 }
891
31c31b8d 892 $ret->{$m} = $req_unavailability_cache{$m}{$v}
893 if $req_unavailability_cache{$m}{$v};
894 }
895
896 $ret;
fb39747c 897}
898
31c31b8d 899
e3fc11e1 900# This is to be called by the author only (automatically in Makefile.PL)
f6b26571 901sub _gen_pod {
47589465 902 my ($class, $distver, $pod_dir) = @_;
31fa1764 903
47589465 904 die "No POD root dir supplied" unless $pod_dir;
31fa1764 905
ccebe1f1 906 $distver ||=
31fa1764 907 eval { require DBIx::Class; DBIx::Class->VERSION; }
908 ||
ccebe1f1 909 die
31fa1764 910"\n\n---------------------------------------------------------------------\n" .
911'Unable to load core DBIx::Class module to determine current version, '.
912'possibly due to missing dependencies. Author-mode autodocumentation ' .
913"halted\n\n" . $@ .
914"\n\n---------------------------------------------------------------------\n"
31fa1764 915 ;
916
3d4c5a84 917 # do not ask for a recent version, use 1.x API calls
47589465 918 # this *may* execute on a smoker with old perl or whatnot
919 require File::Path;
920
921 (my $modfn = __PACKAGE__ . '.pm') =~ s|::|/|g;
922
923 (my $podfn = "$pod_dir/$modfn") =~ s/\.pm$/\.pod/;
924 (my $dir = $podfn) =~ s|/[^/]+$||;
925
926 File::Path::mkpath([$dir]);
927
31c31b8d 928 my $sqltver = $class->req_list_for('deploy')->{'SQL::Translator'}
e3fc11e1 929 or die "Hrmm? No sqlt dep?";
7e3dc46f 930
3ca0dcf0 931
932 my @chunks;
933
934#@@
935#@@ HEADER
936#@@
79b1bf0a 937 push @chunks, <<"EOC";
af4ac504 938#########################################################################
939##################### A U T O G E N E R A T E D ########################
940#########################################################################
941#
942# The contents of this POD file are auto-generated. Any changes you make
943# will be lost. If you need to change the generated text edit _gen_pod()
944# at the end of $modfn
945#
79b1bf0a 946
947=head1 NAME
948
949$class - Optional module dependency specifications (for module authors)
af4ac504 950EOC
3ca0dcf0 951
952
953#@@
954#@@ SYNOPSIS HEADING
955#@@
79b1bf0a 956 push @chunks, <<"EOC";
957=head1 SYNOPSIS
958
959Somewhere in your build-file (e.g. L<ExtUtils::MakeMaker>'s F<Makefile.PL>):
7e3dc46f 960
961 ...
962
79b1bf0a 963 \$EUMM_ARGS{CONFIGURE_REQUIRES} = {
964 \%{ \$EUMM_ARGS{CONFIGURE_REQUIRES} || {} },
965 'DBIx::Class' => '$distver',
966 };
7e3dc46f 967
79b1bf0a 968 ...
7e3dc46f 969
79b1bf0a 970 my %DBIC_DEPLOY_DEPS = %{ eval {
971 require $class;
972 $class->req_list_for('deploy');
973 } || {} };
7e3dc46f 974
79b1bf0a 975 \$EUMM_ARGS{PREREQ_PM} = {
976 \%DBIC_DEPLOY_DEPS,
977 \%{ \$EUMM_ARGS{PREREQ_PM} || {} },
978 };
7e3dc46f 979
980 ...
981
79b1bf0a 982 ExtUtils::MakeMaker::WriteMakefile(\%EUMM_ARGS);
983
984B<Note>: The C<eval> protection within the example is due to support for
985requirements during L<the C<configure> build phase|CPAN::Meta::Spec/Phases>
986not being available on a sufficient portion of production installations of
987Perl. Robust support for such dependency requirements is available in the
988L<CPAN> installer only since version C<1.94_56> first made available for
989production with perl version C<5.12>. It is the belief of the current
990maintainer that support for requirements during the C<configure> build phase
991will not be sufficiently ubiquitous until the B<year 2020> at the earliest,
992hence the extra care demonstrated above. It should also be noted that some
9933rd party installers (e.g. L<cpanminus|App::cpanminus>) do the right thing
994with configure requirements independent from the versions of perl and CPAN
995available.
996EOC
3ca0dcf0 997
998
999#@@
1000#@@ DESCRIPTION HEADING
1001#@@
79b1bf0a 1002 push @chunks, <<'EOC';
1003=head1 DESCRIPTION
1004
f6b26571 1005Some of the less-frequently used features of L<DBIx::Class> have external
1006module dependencies on their own. In order not to burden the average user
79b1bf0a 1007with modules they will never use, these optional dependencies are not included
f6b26571 1008in the base Makefile.PL. Instead an exception with a descriptive message is
79b1bf0a 1009thrown when a specific feature can't find one or several modules required for
1010its operation. This module is the central holding place for the current list
7e3dc46f 1011of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
1012authors alike.
79b1bf0a 1013
1014Dependencies are organized in L<groups|/CURRENT REQUIREMENT GROUPS> where each
1015group can list one or more required modules, with an optional minimum version
e3a7746c 1016(or 0 for any version). In addition groups prefixed with C<test_> can specify
1017a set of environment variables, some (or all) of which are marked as required
1018for the group to be considered by L</req_list_for>
1019
1020Each group name (or a combination thereof) can be used in the
1021L<public methods|/METHODS> as described below.
79b1bf0a 1022EOC
3ca0dcf0 1023
1024
1025#@@
1026#@@ REQUIREMENT GROUPLIST HEADING
1027#@@
79b1bf0a 1028 push @chunks, '=head1 CURRENT REQUIREMENT GROUPS';
f6b26571 1029
31c31b8d 1030 for my $group (sort keys %$dbic_reqs) {
1031 my $p = $dbic_reqs->{$group}{pod}
f6b26571 1032 or next;
1033
31c31b8d 1034 my $modlist = $dbic_reqs->{$group}{req}
f6b26571 1035 or next;
1036
1037 next unless keys %$modlist;
1038
1039 push @chunks, (
1040 "=head2 $p->{title}",
1041 "$p->{desc}",
1042 '=over',
1043 ( map { "=item * $_" . ($modlist->{$_} ? " >= $modlist->{$_}" : '') } (sort keys %$modlist) ),
1044 '=back',
1045 "Requirement group: B<$group>",
1046 );
1047 }
1048
3ca0dcf0 1049
1050#@@
1051#@@ API DOCUMENTATION HEADING
1052#@@
79b1bf0a 1053 push @chunks, <<'EOC';
1054
1055=head1 METHODS
1056
1057=head2 req_group_list
1058
1059=over
1060
1061=item Arguments: none
1062
1063=item Return Value: \%list_of_requirement_groups
1064
1065=back
1066
e3fc11e1 1067This method should be used by DBIx::Class packagers, to get a hashref of all
31c31b8d 1068dependencies B<keyed> by dependency group. Each key (group name), or a combination
1069thereof (as an arrayref) can be supplied to the methods below.
79b1bf0a 1070The B<values> of the returned hash are currently a set of options B<without a
1071well defined structure>. If you have use for any of the contents - contact the
1072maintainers, instead of treating this as public (left alone stable) API.
1073
1074=head2 req_list_for
1075
1076=over
1077
31c31b8d 1078=item Arguments: $group_name | \@group_names
79b1bf0a 1079
31c31b8d 1080=item Return Value: \%set_of_module_version_pairs
79b1bf0a 1081
1082=back
1083
f6b26571 1084This method should be used by DBIx::Class extension authors, to determine the
31c31b8d 1085version of modules a specific set of features requires for this version of
e3a7746c 1086DBIx::Class (regardless of their availability on the system).
1087See the L</SYNOPSIS> for a real-world example.
1088
1089When handling C<test_*> groups this method behaves B<differently> from
1090L</modreq_list_for> below (and is the only such inconsistency among the
1091C<req_*> methods). If a particular group declares as requirements some
1092C<environment variables> and these requirements are not satisfied (the envvars
1093are unset) - then the C<module requirements> of this group are not included in
1094the returned list.
1095
1096=head2 modreq_list_for
1097
1098=over
1099
1100=item Arguments: $group_name | \@group_names
1101
1102=item Return Value: \%set_of_module_version_pairs
1103
1104=back
1105
1106Same as L</req_list_for> but does not take into consideration any
1107C<environment variable requirements> - returns just the list of required
1108modules.
79b1bf0a 1109
1110=head2 req_ok_for
1111
1112=over
1113
31c31b8d 1114=item Arguments: $group_name | \@group_names
79b1bf0a 1115
1116=item Return Value: 1|0
1117
1118=back
1119
e3a7746c 1120Returns true or false depending on whether all modules/envvars required by
1121the group(s) are loadable/set on the system.
79b1bf0a 1122
1123=head2 req_missing_for
1124
1125=over
1126
31c31b8d 1127=item Arguments: $group_name | \@group_names
79b1bf0a 1128
1129=item Return Value: $error_message_string
1130
1131=back
1132
31c31b8d 1133Returns a single-line string suitable for inclusion in larger error messages.
e3a7746c 1134This method would normally be used by DBIx::Class core features, to indicate to
1135the user that they need to install specific modules and/or set specific
1136environment variables before being able to use a specific feature set.
f6b26571 1137
e3fc11e1 1138For example if some of the requirements for C<deploy> are not available,
1139the returned string could look like:
79b1bf0a 1140EOC
f6b26571 1141
79b1bf0a 1142 push @chunks, qq{ "SQL::Translator~>=$sqltver" (see $class documentation for details)};
f6b26571 1143
79b1bf0a 1144 push @chunks, <<'EOC';
f6b26571 1145The author is expected to prepend the necessary text to this message before
e3a7746c 1146returning the actual error seen by the user. See also L</modreq_missing_for>
1147
1148=head2 modreq_missing_for
f6b26571 1149
e3a7746c 1150=over
1151
1152=item Arguments: $group_name | \@group_names
1153
1154=item Return Value: $error_message_string
1155
1156=back
1157
1158Same as L</req_missing_for> except that the error string is guaranteed to be
1159either empty, or contain a set of module requirement specifications suitable
1160for piping to e.g. L<cpanminus|App::cpanminus>. The method explicitly does not
1161attempt to validate the state of required environment variables (if any).
1162
1163For instance if some of the requirements for C<deploy> are not available,
1164the returned string could look like:
1165EOC
1166
1167 push @chunks, qq{ "SQL::Translator~>=$sqltver"};
1168
1169 push @chunks, <<'EOC';
79b1bf0a 1170=head2 die_unless_req_ok_for
1171
1172=over
1173
31c31b8d 1174=item Arguments: $group_name | \@group_names
79b1bf0a 1175
1176=back
1177
31c31b8d 1178Checks if L</req_ok_for> passes for the supplied group(s), and
344f1f52 1179in case of failure throws an exception including the information
1180from L</req_missing_for>.
79b1bf0a 1181
5ffa39c7 1182=head2 modreq_errorlist_for
79b1bf0a 1183
1184=over
1185
31c31b8d 1186=item Arguments: $group_name | \@group_names
79b1bf0a 1187
31c31b8d 1188=item Return Value: \%set_of_loaderrors_per_module
79b1bf0a 1189
1190=back
1191
4a0eed52 1192Returns a hashref containing the actual errors that occurred while attempting
31c31b8d 1193to load each module in the requirement group(s).
5ffa39c7 1194
1195=head2 req_errorlist_for
1196
1197Deprecated method name, equivalent (via proxy) to L</modreq_errorlist_for>.
1198
79b1bf0a 1199EOC
3ca0dcf0 1200
1201#@@
1202#@@ FOOTER
1203#@@
79b1bf0a 1204 push @chunks, <<'EOC';
1205=head1 FURTHER QUESTIONS?
1206
1207Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
1208
1209=head1 COPYRIGHT AND LICENSE
1210
a2bd3796 1211This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
1212by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
1213redistribute it and/or modify it under the same terms as the
1214L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
79b1bf0a 1215EOC
3ca0dcf0 1216
3f5e367a 1217 eval {
1218 open (my $fh, '>', $podfn) or die;
1219 print $fh join ("\n\n", @chunks) or die;
1220 print $fh "\n" or die;
1221 close ($fh) or die;
1222 } or croak( "Unable to write $podfn: " . ( $! || $@ || 'unknown error') );
f6b26571 1223}
1224
8057ed01 12251;