This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update corelist for 5.17.10
[perl5.git] / dist / Module-CoreList / lib / Module / CoreList.pod
CommitLineData
dd4d388c
CBW
1=head1 NAME
2
3Module::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
15 print join ', ', Module::CoreList->find_modules(qr/Data/);
16 # prints 'Data::Dumper'
17 print join ', ', Module::CoreList->find_modules(qr/test::h.*::.*s/i, 5.008008);
18 # prints 'Test::Harness::Assert, Test::Harness::Straps'
19
20 print join ", ", @{ $Module::CoreList::families{5.005} };
21 # prints "5.005, 5.00503, 5.00504"
22
23=head1 DESCRIPTION
24
25Module::CoreList provides information on which core and dual-life modules shipped
26with each version of L<perl>.
27
28It provides a number of mechanisms for querying this information.
29
30There is a utility called L<corelist> provided with this module
31which is a convenient way of querying from the command-line.
32
33There is a functional programming API available for programmers to query
34information.
35
36Programmers may also query the contained hash structures to find relevant
37information.
38
39=head1 FUNCTIONS API
40
41These are the functions that are available, they may either be called as functions or class methods:
42
43 Module::CoreList::first_release('File::Spec'); # as a function
44
45 Module::CoreList->first_release('File::Spec'); # class method
46
47=over
48
49=item C<first_release( MODULE )>
50
51Behaviour since version 2.11
52
53Requires a MODULE name as an argument, returns the perl version when that module first
54appeared in core as ordered by perl version number or undef ( in scalar context )
55or an empty list ( in list context ) if that module is not in core.
56
57=item C<first_release_by_date( MODULE )>
58
59Requires a MODULE name as an argument, returns the perl version when that module first
60appeared in core as ordered by release date or undef ( in scalar context )
61or an empty list ( in list context ) if that module is not in core.
62
63=item C<find_modules( REGEX, [ LIST OF PERLS ] )>
64
65Takes a regex as an argument, returns a list of modules that match the regex given.
66If only a regex is provided applies to all modules in all perl versions. Optionally
67you may provide a list of perl versions to limit the regex search.
68
69=item C<find_version( PERL_VERSION )>
70
71Takes a perl version as an argument. Returns that perl version if it exists or C<undef>
72otherwise.
73
74=item C<is_deprecated( MODULE, PERL_VERSION )>
75
76Available in version 2.22 and above.
77
78Returns true if MODULE is marked as deprecated in PERL_VERSION. If PERL_VERSION is
79omitted, it defaults to the current version of Perl.
80
3df1c36a
CBW
81=item C<deprecated_in( MODULE )>
82
83Available in version 2.77 and above.
84
85Returns the first PERL_VERSION where the MODULE was marked as deprecated. Returns C<undef>
86if the MODULE has not been marked as deprecated.
87
dd4d388c
CBW
88=item C<removed_from( MODULE )>
89
90Available in version 2.32 and above
91
92Takes a module name as an argument, returns the first perl version where that module
93was removed from core. Returns undef if the given module was never in core or remains
94in core.
95
96=item C<removed_from_by_date( MODULE )>
97
98Available in version 2.32 and above
99
100Takes a module name as an argument, returns the first perl version by release date where that module
101was removed from core. Returns undef if the given module was never in core or remains
102in core.
103
797ced94
RS
104=item C<changes_between( PERL_VERSION, PERL_VERSION )>
105
106Available in version 2.66 and above.
107
108Given two perl versions, this returns a list of pairs describing the changes in
109core module content betweent hem. The list is suitable for storing in a hash.
110The keys are library names and the values are hashrefs. Each hashref has an
111entry for one or both of C<left> and C<right>, giving the versions of the
112library in each of the left and right perl distributions.
113
114For example, it might return these data (among others) for the the difference
115between 5.008000 and 5.008001:
116
117 'Pod::ParseLink' => { left => '1.05', right => '1.06' },
118 'Pod::ParseUtils' => { left => '0.22', right => '0.3' },
119 'Pod::Perldoc' => { right => '3.10' },
120 'Pod::Perldoc::BaseTo' => { right => undef },
121
122This shows us two libraries being updated and two being added, one of which has
123an undefined version in the right-hand side version.
124
dd4d388c
CBW
125=back
126
127=head1 DATA STRUCTURES
128
129These are the hash data structures that are available:
130
131=over
132
133=item C<%Module::CoreList::version>
134
135A hash of hashes that is keyed on perl version as indicated
136in $]. The second level hash is module => version pairs.
137
138Note, it is possible for the version of a module to be unspecified,
139whereby the value is C<undef>, so use C<exists $version{$foo}{$bar}> if
140that's what you're testing for.
141
142Starting with 2.10, the special module name C<Unicode> refers to the version of
143the Unicode Character Database bundled with Perl.
144
145=item C<%Module::CoreList::released>
146
147Keyed on perl version this contains ISO
148formatted versions of the release dates, as gleaned from L<perlhist>.
149
150=item C<%Module::CoreList::families>
151
152New, in 1.96, a hash that
153clusters known perl releases by their major versions.
154
155=item C<%Module::CoreList::deprecated>
156
157A hash of hashes keyed on perl version and on module name.
158If a module is defined it indicates that that module is
159deprecated in that perl version and is scheduled for removal
160from core at some future point.
161
162=item C<%Module::CoreList::upstream>
163
164A hash that contains information on where patches should be directed
165for each core module.
166
167UPSTREAM indicates where patches should go. C<undef> implies
168that this hasn't been discussed for the module at hand.
169C<blead> indicates that the copy of the module in the blead
170sources is to be considered canonical, C<cpan> means that the
171module on CPAN is to be patched first. C<first-come> means
172that blead can be patched freely if it is in sync with the
173latest release on CPAN.
174
175=item C<%Module::CoreList::bug_tracker>
176
177A hash that contains information on the appropriate bug tracker
178for each core module.
179
180BUGS is an email or url to post bug reports. For modules with
181UPSTREAM => 'blead', use perl5-porters@perl.org. rt.cpan.org
182appears to automatically provide a URL for CPAN modules; any value
183given here overrides the default:
184http://rt.cpan.org/Public/Dist/Display.html?Name=$ModuleName
185
186=back
187
188=head1 CAVEATS
189
190Module::CoreList currently covers the 5.000, 5.001, 5.002, 5.003_07,
1915.004, 5.004_05, 5.005, 5.005_03, 5.005_04, 5.6.0, 5.6.1, 5.6.2, 5.7.3,
1925.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,
1935.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,
1945.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 1955.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
1965.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,
1975.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 1985.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,
fd3b4111 1995.17.4, 5.17.5, 5.17.6, 5.17.7, 5.17.8, 5.17.9 and 5.17.10 releases of perl.
dd4d388c
CBW
200
201=head1 HISTORY
202
203Moved to Changes file.
204
205=head1 AUTHOR
206
207Richard Clamp E<lt>richardc@unixbeard.netE<gt>
208
209Currently maintained by the perl 5 porters E<lt>perl5-porters@perl.orgE<gt>.
210
211=head1 LICENSE
212
213Copyright (C) 2002-2009 Richard Clamp. All Rights Reserved.
214
215This module is free software; you can redistribute it and/or modify it
216under the same terms as Perl itself.
217
218=head1 SEE ALSO
219
220L<corelist>, L<Module::Info>, L<perl>, L<http://perlpunks.de/corelist>
221
222=cut