This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
055ec0dc4819e037990fc6c4f5dbaf4c436d3f76
[perl5.git] / dist / Module-CoreList / lib / Module / CoreList / Utils.pm
1 package Module::CoreList::Utils;
2
3 use strict;
4 use warnings;
5 use vars qw[$VERSION %utilities];
6 use Module::CoreList;
7 use Module::CoreList::TieHashDelta;
8
9 $VERSION = '5.20150220';
10
11 sub utilities {
12     my $perl = shift;
13     $perl = shift if eval { $perl->isa(__PACKAGE__) };
14     return unless $perl or exists $utilities{$perl};
15     return sort keys %{ $utilities{$perl} };
16 }
17
18 sub first_release_raw {
19     my $util = shift;
20     $util = shift if eval { $util->isa(__PACKAGE__) };
21       #and scalar @_ and $_[0] =~ m#\A[a-zA-Z_][0-9a-zA-Z_]*(?:(::|')[0-9a-zA-Z_]+)*\z#;
22     my $version = shift;
23
24     my @perls = $version
25         ? grep { exists $utilities{$_}{ $util } &&
26                         $utilities{$_}{ $util } ge $version } keys %utilities
27         : grep { exists $utilities{$_}{ $util }             } keys %utilities;
28
29     return grep { exists $Module::CoreList::released{$_} } @perls;
30 }
31
32 sub first_release_by_date {
33     my @perls = &first_release_raw;
34     return unless @perls;
35     return (sort { $Module::CoreList::released{$a} cmp $Module::CoreList::released{$b} } @perls)[0];
36 }
37
38 sub first_release {
39     my @perls = &first_release_raw;
40     return unless @perls;
41     return (sort { $a cmp $b } @perls)[0];
42 }
43
44 sub removed_from {
45   my @perls = &removed_raw;
46   return shift @perls;
47 }
48
49 sub removed_from_by_date {
50   my @perls = sort { $Module::CoreList::released{$a} cmp $Module::CoreList::released{$b} } &removed_raw;
51   return shift @perls;
52 }
53
54 sub removed_raw {
55   my $util = shift;
56   $util = shift if eval { $util->isa(__PACKAGE__) };
57   return unless my @perls = sort { $a cmp $b } first_release_raw($util);
58   @perls = grep { exists $Module::CoreList::released{$_} } @perls;
59   my $last = pop @perls;
60   my @removed = grep { $_ > $last } sort { $a cmp $b } keys %utilities;
61   return @removed;
62 }
63
64 my %delta = (
65     5 => {
66         changed => {
67             'a2p'                   => '1',
68             'c2ph'                  => '1',
69             'cppstdin'              => '1',
70             'find2perl'             => '1',
71             'pstruct'               => '1',
72             's2p'                   => '1',
73         },
74         removed => {
75         }
76     },
77
78     5.001 => {
79         delta_from => 5,
80         changed => {
81             'h2xs'                  => '1',
82         },
83         removed => {
84         }
85     },
86
87     5.002 => {
88         delta_from => 5.001,
89         changed => {
90             'h2ph'                  => '1',
91             'perlbug'               => '1',
92             'perldoc'               => '1',
93             'pod2html'              => '1',
94             'pod2latex'             => '1',
95             'pod2man'               => '1',
96             'pod2text'              => '1',
97         },
98         removed => {
99         }
100     },
101
102     5.00307 => {
103         delta_from => 5.002,
104         changed => {
105             'pl2pm'                 => '1',
106         },
107         removed => {
108            'cppstdin'              => 1,
109            'pstruct'               => 1,
110         }
111     },
112
113     5.004 => {
114         delta_from => 5.00307,
115         changed => {
116             'splain'                => '1',
117         },
118         removed => {
119         }
120     },
121
122     5.005 => {
123         delta_from => 5.00405,
124         changed => {
125             'perlcc'                => '1',
126         },
127         removed => {
128         }
129     },
130
131     5.00503 => {
132         delta_from => 5.005,
133         changed => {
134         },
135         removed => {
136         }
137     },
138
139     5.00405 => {
140         delta_from => 5.004,
141         changed => {
142         },
143         removed => {
144         }
145     },
146
147     5.006 => {
148         delta_from => 5.00504,
149         changed => {
150             'dprofpp'               => '1',
151             'pod2usage'             => '1',
152             'podchecker'            => '1',
153             'podselect'             => '1',
154             'pstruct'               => '1',
155         },
156         removed => {
157         }
158     },
159
160     5.006001 => {
161         delta_from => 5.006,
162         changed => {
163         },
164         removed => {
165         }
166     },
167
168     5.007003 => {
169         delta_from => 5.006002,
170         changed => {
171             'libnetcfg'             => '1',
172             'perlivp'               => '1',
173             'psed'                  => '1',
174             'xsubpp'                => '1',
175         },
176         removed => {
177         }
178     },
179
180     5.008 => {
181         delta_from => 5.007003,
182         changed => {
183             'enc2xs'                => '1',
184             'piconv'                => '1',
185         },
186         removed => {
187         }
188     },
189
190     5.008001 => {
191         delta_from => 5.008,
192         changed => {
193             'cpan'                  => '1',
194         },
195         removed => {
196         }
197     },
198
199     5.009 => {
200         delta_from => 5.008009,
201         changed => {
202         },
203         removed => {
204            'corelist'              => 1,
205            'instmodsh'             => 1,
206            'prove'                 => 1,
207         }
208     },
209
210     5.008002 => {
211         delta_from => 5.008001,
212         changed => {
213         },
214         removed => {
215         }
216     },
217
218     5.006002 => {
219         delta_from => 5.006001,
220         changed => {
221         },
222         removed => {
223         }
224     },
225
226     5.008003 => {
227         delta_from => 5.008002,
228         changed => {
229             'instmodsh'             => '1',
230             'prove'                 => '1',
231         },
232         removed => {
233         }
234     },
235
236     5.00504 => {
237         delta_from => 5.00503,
238         changed => {
239         },
240         removed => {
241         }
242     },
243
244     5.009001 => {
245         delta_from => 5.009,
246         changed => {
247             'instmodsh'             => '1',
248             'prove'                 => '1',
249         },
250         removed => {
251         }
252     },
253
254     5.008004 => {
255         delta_from => 5.008003,
256         changed => {
257         },
258         removed => {
259         }
260     },
261
262     5.008005 => {
263         delta_from => 5.008004,
264         changed => {
265         },
266         removed => {
267         }
268     },
269
270     5.008006 => {
271         delta_from => 5.008005,
272         changed => {
273         },
274         removed => {
275         }
276     },
277
278     5.009002 => {
279         delta_from => 5.009001,
280         changed => {
281             'corelist'              => '1',
282         },
283         removed => {
284         }
285     },
286
287     5.008007 => {
288         delta_from => 5.008006,
289         changed => {
290         },
291         removed => {
292         }
293     },
294
295     5.009003 => {
296         delta_from => 5.009002,
297         changed => {
298             'ptar'                  => '1',
299             'ptardiff'              => '1',
300             'shasum'                => '1',
301         },
302         removed => {
303         }
304     },
305
306     5.008008 => {
307         delta_from => 5.008007,
308         changed => {
309         },
310         removed => {
311         }
312     },
313
314     5.009004 => {
315         delta_from => 5.009003,
316         changed => {
317             'config_data'           => '1',
318         },
319         removed => {
320         }
321     },
322
323     5.009005 => {
324         delta_from => 5.009004,
325         changed => {
326             'cpan2dist'             => '1',
327             'cpanp'                 => '1',
328             'cpanp-run-perl'        => '1',
329         },
330         removed => {
331            'perlcc'                => 1,
332         }
333     },
334
335     5.010000 => {
336         delta_from => 5.009005,
337         changed => {
338         },
339         removed => {
340         }
341     },
342
343     5.008009 => {
344         delta_from => 5.008008,
345         changed => {
346             'corelist'              => '1',
347         },
348         removed => {
349         }
350     },
351
352     5.010001 => {
353         delta_from => 5.010000,
354         changed => {
355         },
356         removed => {
357         }
358     },
359
360     5.011 => {
361         delta_from => 5.010001,
362         changed => {
363         },
364         removed => {
365         }
366     },
367
368     5.011001 => {
369         delta_from => 5.011,
370         changed => {
371         },
372         removed => {
373         }
374     },
375
376     5.011002 => {
377         delta_from => 5.011001,
378         changed => {
379             'perlthanks'            => '1',
380         },
381         removed => {
382         }
383     },
384
385     5.011003 => {
386         delta_from => 5.011002,
387         changed => {
388         },
389         removed => {
390         }
391     },
392
393     5.011004 => {
394         delta_from => 5.011003,
395         changed => {
396         },
397         removed => {
398         }
399     },
400
401     5.011005 => {
402         delta_from => 5.011004,
403         changed => {
404         },
405         removed => {
406         }
407     },
408
409     5.012 => {
410         delta_from => 5.011005,
411         changed => {
412         },
413         removed => {
414         }
415     },
416
417     5.013 => {
418         delta_from => 5.012005,
419         changed => {
420         },
421         removed => {
422         }
423     },
424
425     5.012001 => {
426         delta_from => 5.012,
427         changed => {
428         },
429         removed => {
430         }
431     },
432
433     5.013001 => {
434         delta_from => 5.013,
435         changed => {
436         },
437         removed => {
438         }
439     },
440
441     5.013002 => {
442         delta_from => 5.013001,
443         changed => {
444         },
445         removed => {
446         }
447     },
448
449     5.013003 => {
450         delta_from => 5.013002,
451         changed => {
452         },
453         removed => {
454         }
455     },
456
457     5.013004 => {
458         delta_from => 5.013003,
459         changed => {
460         },
461         removed => {
462         }
463     },
464
465     5.012002 => {
466         delta_from => 5.012001,
467         changed => {
468         },
469         removed => {
470         }
471     },
472
473     5.013005 => {
474         delta_from => 5.013004,
475         changed => {
476         },
477         removed => {
478         }
479     },
480
481     5.013006 => {
482         delta_from => 5.013005,
483         changed => {
484         },
485         removed => {
486         }
487     },
488
489     5.013007 => {
490         delta_from => 5.013006,
491         changed => {
492             'ptargrep'              => '1',
493         },
494         removed => {
495         }
496     },
497
498     5.013008 => {
499         delta_from => 5.013007,
500         changed => {
501         },
502         removed => {
503         }
504     },
505
506     5.013009 => {
507         delta_from => 5.013008,
508         changed => {
509             'json_pp'               => '1',
510         },
511         removed => {
512         }
513     },
514
515     5.012003 => {
516         delta_from => 5.012002,
517         changed => {
518         },
519         removed => {
520         }
521     },
522
523     5.013010 => {
524         delta_from => 5.013009,
525         changed => {
526         },
527         removed => {
528         }
529     },
530
531     5.013011 => {
532         delta_from => 5.013010,
533         changed => {
534         },
535         removed => {
536         }
537     },
538
539     5.014 => {
540         delta_from => 5.013011,
541         changed => {
542         },
543         removed => {
544         }
545     },
546
547     5.014001 => {
548         delta_from => 5.014,
549         changed => {
550         },
551         removed => {
552         }
553     },
554
555     5.015 => {
556         delta_from => 5.014004,
557         changed => {
558         },
559         removed => {
560            'dprofpp'               => 1,
561         }
562     },
563
564     5.012004 => {
565         delta_from => 5.012003,
566         changed => {
567         },
568         removed => {
569         }
570     },
571
572     5.015001 => {
573         delta_from => 5.015,
574         changed => {
575         },
576         removed => {
577         }
578     },
579
580     5.015002 => {
581         delta_from => 5.015001,
582         changed => {
583         },
584         removed => {
585         }
586     },
587
588     5.015003 => {
589         delta_from => 5.015002,
590         changed => {
591         },
592         removed => {
593         }
594     },
595
596     5.014002 => {
597         delta_from => 5.014001,
598         changed => {
599         },
600         removed => {
601         }
602     },
603
604     5.015004 => {
605         delta_from => 5.015003,
606         changed => {
607         },
608         removed => {
609         }
610     },
611
612     5.015005 => {
613         delta_from => 5.015004,
614         changed => {
615         },
616         removed => {
617         }
618     },
619
620     5.015006 => {
621         delta_from => 5.015005,
622         changed => {
623             'zipdetails'            => '1',
624         },
625         removed => {
626         }
627     },
628
629     5.015007 => {
630         delta_from => 5.015006,
631         changed => {
632         },
633         removed => {
634         }
635     },
636
637     5.015008 => {
638         delta_from => 5.015007,
639         changed => {
640         },
641         removed => {
642         }
643     },
644
645     5.015009 => {
646         delta_from => 5.015008,
647         changed => {
648         },
649         removed => {
650         }
651     },
652
653     5.016 => {
654         delta_from => 5.015009,
655         changed => {
656         },
657         removed => {
658         }
659     },
660
661     5.017 => {
662         delta_from => 5.016003,
663         changed => {
664         },
665         removed => {
666         }
667     },
668
669     5.017001 => {
670         delta_from => 5.017,
671         changed => {
672         },
673         removed => {
674         }
675     },
676
677     5.017002 => {
678         delta_from => 5.017001,
679         changed => {
680         },
681         removed => {
682         }
683     },
684
685     5.016001 => {
686         delta_from => 5.016,
687         changed => {
688         },
689         removed => {
690         }
691     },
692
693     5.017003 => {
694         delta_from => 5.017002,
695         changed => {
696         },
697         removed => {
698         }
699     },
700
701     5.017004 => {
702         delta_from => 5.017003,
703         changed => {
704         },
705         removed => {
706         }
707     },
708
709     5.014003 => {
710         delta_from => 5.014002,
711         changed => {
712         },
713         removed => {
714         }
715     },
716
717     5.017005 => {
718         delta_from => 5.017004,
719         changed => {
720         },
721         removed => {
722         }
723     },
724
725     5.016002 => {
726         delta_from => 5.016001,
727         changed => {
728         },
729         removed => {
730         }
731     },
732
733     5.012005 => {
734         delta_from => 5.012004,
735         changed => {
736         },
737         removed => {
738         }
739     },
740
741     5.017006 => {
742         delta_from => 5.017005,
743         changed => {
744         },
745         removed => {
746         }
747     },
748
749     5.017007 => {
750         delta_from => 5.017006,
751         changed => {
752         },
753         removed => {
754         }
755     },
756
757     5.017008 => {
758         delta_from => 5.017007,
759         changed => {
760         },
761         removed => {
762         }
763     },
764
765     5.017009 => {
766         delta_from => 5.017008,
767         changed => {
768         },
769         removed => {
770         }
771     },
772
773     5.014004 => {
774         delta_from => 5.014003,
775         changed => {
776         },
777         removed => {
778         }
779     },
780
781     5.016003 => {
782         delta_from => 5.016002,
783         changed => {
784         },
785         removed => {
786         }
787     },
788
789     5.017010 => {
790         delta_from => 5.017009,
791         changed => {
792         },
793         removed => {
794         }
795     },
796
797     5.017011 => {
798         delta_from => 5.017010,
799         changed => {
800         },
801         removed => {
802         }
803     },
804     5.018000 => {
805         delta_from => 5.017011,
806         changed => {
807         },
808         removed => {
809         }
810     },
811     5.018001 => {
812         delta_from => 5.018000,
813         changed => {
814         },
815         removed => {
816         }
817     },
818     5.018002 => {
819         delta_from => 5.018001,
820         changed => {
821         },
822         removed => {
823         }
824     },
825     5.018003 => {
826         delta_from => 5.018000,
827         changed => {
828         },
829         removed => {
830         }
831     },
832     5.018004 => {
833         delta_from => 5.018000,
834         changed => {
835         },
836         removed => {
837         }
838     },
839     5.019000 => {
840         delta_from => 5.018000,
841         changed => {
842         },
843         removed => {
844             'cpan2dist'             => '1',
845             'cpanp'                 => '1',
846             'cpanp-run-perl'        => '1',
847             'pod2latex'             => '1',
848         }
849     },
850     5.019001 => {
851         delta_from => 5.019000,
852         changed => {
853         },
854         removed => {
855         }
856     },
857     5.019002 => {
858         delta_from => 5.019001,
859         changed => {
860         },
861         removed => {
862         }
863     },
864     5.019003 => {
865         delta_from => 5.019002,
866         changed => {
867         },
868         removed => {
869         }
870     },
871     5.019004 => {
872         delta_from => 5.019003,
873         changed => {
874         },
875         removed => {
876         }
877     },
878     5.019005 => {
879         delta_from => 5.019004,
880         changed => {
881         },
882         removed => {
883         }
884     },
885     5.019006 => {
886         delta_from => 5.019005,
887         changed => {
888         },
889         removed => {
890         }
891     },
892     5.019007 => {
893         delta_from => 5.019006,
894         changed => {
895         },
896         removed => {
897         }
898     },
899     5.019008 => {
900         delta_from => 5.019007,
901         changed => {
902         },
903         removed => {
904         }
905     },
906     5.019009 => {
907         delta_from => 5.019008,
908         changed => {
909         },
910         removed => {
911         }
912     },
913     5.019010 => {
914         delta_from => 5.019009,
915         changed => {
916         },
917         removed => {
918         }
919     },
920     5.019011 => {
921         delta_from => 5.019010,
922         changed => {
923         },
924         removed => {
925         }
926     },
927     5.020000 => {
928         delta_from => 5.019011,
929         changed => {
930         },
931         removed => {
932         }
933     },
934     5.021000 => {
935         delta_from => 5.020000,
936         changed => {
937         },
938         removed => {
939         }
940     },
941     5.021001 => {
942         delta_from => 5.021000,
943         changed => {
944         },
945         removed => {
946             'a2p'                   => 1,
947             'config_data'           => 1,
948             'find2perl'             => 1,
949             'psed'                  => 1,
950             's2p'                   => 1,
951         }
952     },
953     5.021002 => {
954         delta_from => 5.021001,
955         changed => {
956         },
957         removed => {
958         }
959     },
960     5.021003 => {
961         delta_from => 5.021002,
962         changed => {
963         },
964         removed => {
965         }
966     },
967     5.020001 => {
968         delta_from => 5.02,
969         changed => {
970         },
971         removed => {
972         }
973     },
974     5.021004 => {
975         delta_from => 5.021003,
976         changed => {
977         },
978         removed => {
979         }
980     },
981     5.021005 => {
982         delta_from => 5.021004,
983         changed => {
984         },
985         removed => {
986         }
987     },
988     5.021006 => {
989         delta_from => 5.021005,
990         changed => {
991         },
992         removed => {
993         }
994     },
995     5.021007 => {
996         delta_from => 5.021006,
997         changed => {
998         },
999         removed => {
1000         }
1001     },
1002     5.021008 => {
1003         delta_from => 5.021007,
1004         changed => {
1005         },
1006         removed => {
1007         }
1008     },
1009     5.020002 => {
1010         delta_from => 5.020001,
1011         changed => {
1012         },
1013         removed => {
1014         }
1015     },
1016     5.021009 => {
1017         delta_from => 5.021008,
1018         changed => {
1019             'encguess'              => '1',
1020         },
1021         removed => {
1022         }
1023     },
1024     5.021010 => {
1025         delta_from => 5.021009,
1026         changed => {
1027         },
1028         removed => {
1029         }
1030     },
1031 );
1032
1033 for my $version (sort { $a <=> $b } keys %delta) {
1034     my $data = $delta{$version};
1035
1036     tie %{$utilities{$version}}, 'Module::CoreList::TieHashDelta',
1037         $data->{changed}, $data->{removed},
1038         $data->{delta_from} ? $utilities{$data->{delta_from}} : undef;
1039 }
1040
1041 # Create aliases with trailing zeros for $] use
1042
1043 $utilities{'5.000'} = $utilities{5};
1044
1045 _create_aliases(\%utilities);
1046
1047 sub _create_aliases {
1048     my ($hash) = @_;
1049
1050     for my $version (keys %$hash) {
1051         next unless $version >= 5.010;
1052
1053         my $padded = sprintf "%0.6f", $version;
1054
1055         # If the version in string form isn't the same as the numeric version,
1056         # alias it.
1057         if ($padded ne $version && $version == $padded) {
1058             $hash->{$padded} = $hash->{$version};
1059         }
1060     }
1061 }
1062
1063 'foo';
1064
1065 =pod
1066
1067 =head1 NAME
1068
1069 Module::CoreList::Utils - what utilities shipped with versions of perl
1070
1071 =head1 SYNOPSIS
1072
1073  use Module::CoreList::Utils;
1074
1075  print $Module::CoreList::Utils::utilities{5.009003}{ptar}; # prints 1
1076
1077  print Module::CoreList::Utils->first_release('corelist');           # prints 5.008009
1078  print Module::CoreList::Utils->first_release_by_date('corelist');   # prints 5.009002
1079
1080 =head1 DESCRIPTION
1081
1082 Module::CoreList::Utils provides information on which core and dual-life utilities shipped
1083 with each version of L<perl>.
1084
1085 It provides a number of mechanisms for querying this information.
1086
1087 There is a functional programming API available for programmers to query
1088 information.
1089
1090 Programmers may also query the contained hash structure to find relevant
1091 information.
1092
1093 =head1 FUNCTIONS API
1094
1095 These are the functions that are available, they may either be called as functions or class methods:
1096
1097   Module::CoreList::Utils::first_release('corelist'); # as a function
1098
1099   Module::CoreList::Utils->first_release('corelist'); # class method
1100
1101 =over
1102
1103 =item C<utilities>
1104
1105 Requires a perl version as an argument, returns a list of utilities that shipped with
1106 that version of perl, or undef/empty list if that perl doesn't exist.
1107
1108 =item C<first_release( UTILITY )>
1109
1110 Requires a UTILITY name as an argument, returns the perl version when that utility first
1111 appeared in core as ordered by perl version number or undef ( in scalar context )
1112 or an empty list ( in list context ) if that utility is not in core.
1113
1114 =item C<first_release_by_date( UTILITY )>
1115
1116 Requires a UTILITY name as an argument, returns the perl version when that utility first
1117 appeared in core as ordered by release date or undef ( in scalar context )
1118 or an empty list ( in list context ) if that utility is not in core.
1119
1120 =item C<removed_from( UTILITY )>
1121
1122 Takes a UTILITY name as an argument, returns the first perl version where that utility
1123 was removed from core. Returns undef if the given utility was never in core or remains
1124 in core.
1125
1126 =item C<removed_from_by_date( UTILITY )>
1127
1128 Takes a UTILITY name as an argument, returns the first perl version by release date where that
1129 utility was removed from core. Returns undef if the given utility was never in core or remains
1130 in core.
1131
1132 =back
1133
1134 =head1 DATA STRUCTURES
1135
1136 These are the hash data structures that are available:
1137
1138 =over
1139
1140 =item C<%Module::CoreList::Utils::utilities>
1141
1142 A hash of hashes that is keyed on perl version as indicated
1143 in $].  The second level hash is utility / defined pairs.
1144
1145 =back
1146
1147 =head1 AUTHOR
1148
1149 Chris C<BinGOs> Williams <chris@bingosnet.co.uk>
1150
1151 Currently maintained by the perl 5 porters E<lt>perl5-porters@perl.orgE<gt>.
1152
1153 This module is the result of archaeology undertaken during QA Hackathon
1154 in Lancaster, April 2013.
1155
1156 =head1 LICENSE
1157
1158 Copyright (C) 2013 Chris Williams.  All Rights Reserved.
1159
1160 This module is free software; you can redistribute it and/or modify it
1161 under the same terms as Perl itself.
1162
1163 =head1 SEE ALSO
1164
1165 L<corelist>, L<Module::CoreList>, L<perl>, L<http://perlpunks.de/corelist>
1166
1167 =cut