Commit | Line | Data |
---|---|---|
dd4d388c CBW |
1 | =head1 NAME |
2 | ||
3 | Module::CoreList - what modules shipped with versions of perl | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | use Module::CoreList; | |
8 | ||
9 | print $Module::CoreList::version{5.00503}{CPAN}; # prints 1.48 | |
10 | ||
11 | print Module::CoreList->first_release('File::Spec'); # prints 5.00405 | |
12 | print Module::CoreList->first_release_by_date('File::Spec'); # prints 5.005 | |
13 | print Module::CoreList->first_release('File::Spec', 0.82); # prints 5.006001 | |
14 | ||
2a21e867 NB |
15 | if (Module::CoreList::is_core('File::Spec')) { |
16 | print "File::Spec is a core module\n"; | |
17 | } | |
18 | ||
dd4d388c CBW |
19 | print join ', ', Module::CoreList->find_modules(qr/Data/); |
20 | # prints 'Data::Dumper' | |
21 | print join ', ', Module::CoreList->find_modules(qr/test::h.*::.*s/i, 5.008008); | |
22 | # prints 'Test::Harness::Assert, Test::Harness::Straps' | |
23 | ||
24 | print join ", ", @{ $Module::CoreList::families{5.005} }; | |
25 | # prints "5.005, 5.00503, 5.00504" | |
26 | ||
27 | =head1 DESCRIPTION | |
28 | ||
29 | Module::CoreList provides information on which core and dual-life modules shipped | |
30 | with each version of L<perl>. | |
31 | ||
32 | It provides a number of mechanisms for querying this information. | |
33 | ||
34 | There is a utility called L<corelist> provided with this module | |
35 | which is a convenient way of querying from the command-line. | |
36 | ||
37 | There is a functional programming API available for programmers to query | |
38 | information. | |
39 | ||
40 | Programmers may also query the contained hash structures to find relevant | |
41 | information. | |
42 | ||
43 | =head1 FUNCTIONS API | |
44 | ||
45 | These are the functions that are available, they may either be called as functions or class methods: | |
46 | ||
47 | Module::CoreList::first_release('File::Spec'); # as a function | |
48 | ||
49 | Module::CoreList->first_release('File::Spec'); # class method | |
50 | ||
51 | =over | |
52 | ||
53 | =item C<first_release( MODULE )> | |
54 | ||
55 | Behaviour since version 2.11 | |
56 | ||
57 | Requires a MODULE name as an argument, returns the perl version when that module first | |
58 | appeared in core as ordered by perl version number or undef ( in scalar context ) | |
59 | or an empty list ( in list context ) if that module is not in core. | |
60 | ||
61 | =item C<first_release_by_date( MODULE )> | |
62 | ||
63 | Requires a MODULE name as an argument, returns the perl version when that module first | |
64 | appeared in core as ordered by release date or undef ( in scalar context ) | |
65 | or an empty list ( in list context ) if that module is not in core. | |
66 | ||
67 | =item C<find_modules( REGEX, [ LIST OF PERLS ] )> | |
68 | ||
69 | Takes a regex as an argument, returns a list of modules that match the regex given. | |
70 | If only a regex is provided applies to all modules in all perl versions. Optionally | |
71 | you may provide a list of perl versions to limit the regex search. | |
72 | ||
73 | =item C<find_version( PERL_VERSION )> | |
74 | ||
75 | Takes a perl version as an argument. Returns that perl version if it exists or C<undef> | |
76 | otherwise. | |
77 | ||
2a21e867 NB |
78 | =item C<is_core( MODULE, [ MODULE_VERSION, [ PERL_VERSION ] ] )> |
79 | ||
80 | Available in version 2.99 and above. | |
81 | ||
82 | Returns true if MODULE was bundled with the specified version of Perl. | |
83 | You can optionally specify a minimum version of the module, | |
84 | and can also specify a version of Perl. | |
85 | If a version of Perl isn't specified, | |
86 | C<is_core()> will use the version of Perl that is running (ie C<$^V>). | |
87 | ||
88 | If you want to specify the version of Perl, but don't care about | |
89 | the version of the module, pass C<undef> for the module version: | |
90 | ||
dd4d388c CBW |
91 | =item C<is_deprecated( MODULE, PERL_VERSION )> |
92 | ||
93 | Available in version 2.22 and above. | |
94 | ||
95 | Returns true if MODULE is marked as deprecated in PERL_VERSION. If PERL_VERSION is | |
96 | omitted, it defaults to the current version of Perl. | |
97 | ||
3df1c36a CBW |
98 | =item C<deprecated_in( MODULE )> |
99 | ||
100 | Available in version 2.77 and above. | |
101 | ||
102 | Returns the first PERL_VERSION where the MODULE was marked as deprecated. Returns C<undef> | |
103 | if the MODULE has not been marked as deprecated. | |
104 | ||
dd4d388c CBW |
105 | =item C<removed_from( MODULE )> |
106 | ||
107 | Available in version 2.32 and above | |
108 | ||
109 | Takes a module name as an argument, returns the first perl version where that module | |
110 | was removed from core. Returns undef if the given module was never in core or remains | |
111 | in core. | |
112 | ||
113 | =item C<removed_from_by_date( MODULE )> | |
114 | ||
115 | Available in version 2.32 and above | |
116 | ||
117 | Takes a module name as an argument, returns the first perl version by release date where that module | |
118 | was removed from core. Returns undef if the given module was never in core or remains | |
119 | in core. | |
120 | ||
797ced94 RS |
121 | =item C<changes_between( PERL_VERSION, PERL_VERSION )> |
122 | ||
123 | Available in version 2.66 and above. | |
124 | ||
125 | Given two perl versions, this returns a list of pairs describing the changes in | |
a1b61b28 | 126 | core module content between them. The list is suitable for storing in a hash. |
797ced94 RS |
127 | The keys are library names and the values are hashrefs. Each hashref has an |
128 | entry for one or both of C<left> and C<right>, giving the versions of the | |
129 | library in each of the left and right perl distributions. | |
130 | ||
f5ee86c7 | 131 | For example, it might return these data (among others) for the difference |
797ced94 RS |
132 | between 5.008000 and 5.008001: |
133 | ||
134 | 'Pod::ParseLink' => { left => '1.05', right => '1.06' }, | |
135 | 'Pod::ParseUtils' => { left => '0.22', right => '0.3' }, | |
136 | 'Pod::Perldoc' => { right => '3.10' }, | |
137 | 'Pod::Perldoc::BaseTo' => { right => undef }, | |
138 | ||
139 | This shows us two libraries being updated and two being added, one of which has | |
140 | an undefined version in the right-hand side version. | |
141 | ||
dd4d388c CBW |
142 | =back |
143 | ||
144 | =head1 DATA STRUCTURES | |
145 | ||
146 | These are the hash data structures that are available: | |
147 | ||
148 | =over | |
149 | ||
150 | =item C<%Module::CoreList::version> | |
151 | ||
152 | A hash of hashes that is keyed on perl version as indicated | |
153 | in $]. The second level hash is module => version pairs. | |
154 | ||
155 | Note, it is possible for the version of a module to be unspecified, | |
156 | whereby the value is C<undef>, so use C<exists $version{$foo}{$bar}> if | |
157 | that's what you're testing for. | |
158 | ||
159 | Starting with 2.10, the special module name C<Unicode> refers to the version of | |
160 | the Unicode Character Database bundled with Perl. | |
161 | ||
c676c838 CBW |
162 | =item C<%Module::CoreList::delta> |
163 | ||
164 | Available in version 3.00 and above. | |
165 | ||
166 | C<%Module::CoreList::version> is implemented via C<Module::CoreList::TieHashDelta> | |
167 | using this hash of delta changes. | |
168 | ||
169 | It is a hash of hashes that is keyed on perl version. Each keyed hash will have the | |
170 | following keys: | |
171 | ||
172 | delta_from - a previous perl version that the changes are based on | |
173 | changed - a hash of module/versions that have changed | |
174 | removed - a hash of modules that have been removed | |
175 | ||
dd4d388c CBW |
176 | =item C<%Module::CoreList::released> |
177 | ||
178 | Keyed on perl version this contains ISO | |
179 | formatted versions of the release dates, as gleaned from L<perlhist>. | |
180 | ||
181 | =item C<%Module::CoreList::families> | |
182 | ||
183 | New, in 1.96, a hash that | |
184 | clusters known perl releases by their major versions. | |
185 | ||
186 | =item C<%Module::CoreList::deprecated> | |
187 | ||
188 | A hash of hashes keyed on perl version and on module name. | |
189 | If a module is defined it indicates that that module is | |
190 | deprecated in that perl version and is scheduled for removal | |
191 | from core at some future point. | |
192 | ||
193 | =item C<%Module::CoreList::upstream> | |
194 | ||
195 | A hash that contains information on where patches should be directed | |
196 | for each core module. | |
197 | ||
198 | UPSTREAM indicates where patches should go. C<undef> implies | |
199 | that this hasn't been discussed for the module at hand. | |
200 | C<blead> indicates that the copy of the module in the blead | |
201 | sources is to be considered canonical, C<cpan> means that the | |
202 | module on CPAN is to be patched first. C<first-come> means | |
203 | that blead can be patched freely if it is in sync with the | |
204 | latest release on CPAN. | |
205 | ||
206 | =item C<%Module::CoreList::bug_tracker> | |
207 | ||
208 | A hash that contains information on the appropriate bug tracker | |
209 | for each core module. | |
210 | ||
211 | BUGS is an email or url to post bug reports. For modules with | |
212 | UPSTREAM => 'blead', use perl5-porters@perl.org. rt.cpan.org | |
213 | appears to automatically provide a URL for CPAN modules; any value | |
214 | given here overrides the default: | |
215 | http://rt.cpan.org/Public/Dist/Display.html?Name=$ModuleName | |
216 | ||
217 | =back | |
218 | ||
219 | =head1 CAVEATS | |
220 | ||
221 | Module::CoreList currently covers the 5.000, 5.001, 5.002, 5.003_07, | |
222 | 5.004, 5.004_05, 5.005, 5.005_03, 5.005_04, 5.6.0, 5.6.1, 5.6.2, 5.7.3, | |
223 | 5.8.0, 5.8.1, 5.8.2, 5.8.3, 5.8.4, 5.8.5, 5.8.6, 5.8.7, 5.8.8, 5.8.9, | |
224 | 5.9.0, 5.9.1, 5.9.2, 5.9.3, 5.9.4, 5.9.5, 5.10.0, 5.10.1, 5.11.0, 5.11.1, | |
225 | 5.11.2, 5.11.3, 5.11.4, 5.11.5, 5.12.0, 5.12.1, 5.12.2, 5.12.3, 5.12.4, | |
3df1c36a | 226 | 5.12.5, 5.13.0, 5.13.1, 5.13.2, 5.13.3, 5.13.4, 5.13.5, 5.13.6, 5.13.7, |
11d2dbf3 CBW |
227 | 5.13.8, 5.13.9, 5.13.10, 5.13.11, 5.14.0, 5.14.1, 5.14.2 5.14.3, 5.14.4, |
228 | 5.15.0, 5.15.1, 5.15.2, 5.15.3, 5.15.4, 5.15.5, 5.15.6, 5.15.7, 5.15.8, | |
cd98b2f5 | 229 | 5.15.9, 5.16.0, 5.16.1, 5.16.2, 5.16.3, 5.17.0, 5.17.1, 5.17.2, 5.17.3, |
1f0ad552 | 230 | 5.17.4, 5.17.5, 5.17.6, 5.17.7, 5.17.8, 5.17.9, 5.17.10, 5.17.11, 5.18.0, |
365f8c3e | 231 | 5.19.0, 5.19.1, 5.19.2, 5.19.3, 5.19.4, 5.19.5, 5.19.6, 5.19.7 and 5.19.8 releases of perl. |
dd4d388c CBW |
232 | |
233 | =head1 HISTORY | |
234 | ||
235 | Moved to Changes file. | |
236 | ||
237 | =head1 AUTHOR | |
238 | ||
239 | Richard Clamp E<lt>richardc@unixbeard.netE<gt> | |
240 | ||
241 | Currently maintained by the perl 5 porters E<lt>perl5-porters@perl.orgE<gt>. | |
242 | ||
243 | =head1 LICENSE | |
244 | ||
245 | Copyright (C) 2002-2009 Richard Clamp. All Rights Reserved. | |
246 | ||
247 | This module is free software; you can redistribute it and/or modify it | |
248 | under the same terms as Perl itself. | |
249 | ||
250 | =head1 SEE ALSO | |
251 | ||
252 | L<corelist>, L<Module::Info>, L<perl>, L<http://perlpunks.de/corelist> | |
253 | ||
254 | =cut |