Module::CoreList(3pm)

1Module::CoreList(3)   User Contributed Perl Documentation  Module::CoreList(3)
2
3
4

NAME

6       Module::CoreList - what modules shipped with versions of perl
7

SYNOPSIS

9        use Module::CoreList;
10
11        print $Module::CoreList::version{5.00503}{CPAN}; # prints 1.48
12
13        print Module::CoreList->first_release('File::Spec');
14        # prints 5.00405
15
16        print Module::CoreList->first_release_by_date('File::Spec');
17        # prints 5.005
18
19        print Module::CoreList->first_release('File::Spec', 0.82);
20        # prints 5.006001
21
22        if (Module::CoreList::is_core('File::Spec')) {
23          print "File::Spec is a core module\n";
24        }
25
26        print join ', ', Module::CoreList->find_modules(qr/Data/);
27           # prints 'Data::Dumper'
28        print join ', ',
29                 Module::CoreList->find_modules(qr/test::h.*::.*s/i, 5.008008);
30           # prints 'Test::Harness::Assert, Test::Harness::Straps'
31
32        print join ", ", @{ $Module::CoreList::families{5.005} };
33           # prints "5.005, 5.00503, 5.00504"
34

DESCRIPTION

36       Module::CoreList provides information on which core and dual-life
37       modules shipped with each version of perl.
38
39       It provides a number of mechanisms for querying this information.
40
41       There is a utility called corelist provided with this module which is a
42       convenient way of querying from the command-line.
43
44       There is a functional programming API available for programmers to
45       query information.
46
47       Programmers may also query the contained hash structures to find
48       relevant information.
49

FUNCTIONS API

51       These are the functions that are available, they may either be called
52       as functions or class methods:
53
54         Module::CoreList::first_release('File::Spec'); # as a function
55
56         Module::CoreList->first_release('File::Spec'); # class method
57
58       "first_release( MODULE )"
59           Behaviour since version 2.11
60
61           Requires a MODULE name as an argument, returns the perl version
62           when that module first appeared in core as ordered by perl version
63           number or undef ( in scalar context ) or an empty list ( in list
64           context ) if that module is not in core.
65
66       "first_release_by_date( MODULE )"
67           Requires a MODULE name as an argument, returns the perl version
68           when that module first appeared in core as ordered by release date
69           or undef ( in scalar context ) or an empty list ( in list context )
70           if that module is not in core.
71
72       "find_modules( REGEX, [ LIST OF PERLS ] )"
73           Takes a regex as an argument, returns a list of modules that match
74           the regex given.  If only a regex is provided applies to all
75           modules in all perl versions. Optionally you may provide a list of
76           perl versions to limit the regex search.
77
78       "find_version( PERL_VERSION )"
79           Takes a perl version as an argument. Upon successful completion,
80           returns a reference to a hash.  Each element of that hash has a key
81           which is the name of a module (e.g., 'File::Path') shipped with
82           that version of perl and a value which is the version number (e.g.,
83           '2.09') of that module which shipped with that version of perl .
84           Returns "undef" otherwise.
85
86       "is_core( MODULE, [ MODULE_VERSION, [ PERL_VERSION ] ] )"
87           Available in version 2.99 and above.
88
89           Returns true if MODULE was bundled with the specified version of
90           Perl.  You can optionally specify a minimum version of the module,
91           and can also specify a version of Perl.  If a version of Perl isn't
92           specified, "is_core()" will use the numeric version of Perl that is
93           running (ie $]).
94
95           If you want to specify the version of Perl, but don't care about
96           the version of the module, pass "undef" for the module version:
97
98       "is_deprecated( MODULE, PERL_VERSION )"
99           Available in version 2.22 and above.
100
101           Returns true if MODULE is marked as deprecated in PERL_VERSION.  If
102           PERL_VERSION is omitted, it defaults to the current version of
103           Perl.
104
105       "deprecated_in( MODULE )"
106           Available in version 2.77 and above.
107
108           Returns the first perl version where the MODULE was marked as
109           deprecated. Returns "undef" if the MODULE has not been marked as
110           deprecated.
111
112       "removed_from( MODULE )"
113           Available in version 2.32 and above
114
115           Takes a module name as an argument, returns the first perl version
116           where that module was removed from core. Returns undef if the given
117           module was never in core or remains in core.
118
119       "removed_from_by_date( MODULE )"
120           Available in version 2.32 and above
121
122           Takes a module name as an argument, returns the first perl version
123           by release date where that module was removed from core. Returns
124           undef if the given module was never in core or remains in core.
125
126       "changes_between( PERL_VERSION, PERL_VERSION )"
127           Available in version 2.66 and above.
128
129           Given two perl versions, this returns a list of pairs describing
130           the changes in core module content between them.  The list is
131           suitable for storing in a hash.  The keys are library names and the
132           values are hashrefs.  Each hashref has an entry for one or both of
133           "left" and "right", giving the versions of the library in each of
134           the left and right perl distributions.
135
136           For example, it might return these data (among others) for the
137           difference between 5.008000 and 5.008001:
138
139             'Pod::ParseLink'  => { left => '1.05', right => '1.06' },
140             'Pod::ParseUtils' => { left => '0.22', right => '0.3'  },
141             'Pod::Perldoc'    => {                 right => '3.10' },
142             'Pod::Perldoc::BaseTo' => {            right => undef  },
143
144           This shows us two libraries being updated and two being added, one
145           of which has an undefined version in the right-hand side version.
146

DATA STRUCTURES

148       These are the hash data structures that are available:
149
150       %Module::CoreList::version
151           A hash of hashes that is keyed on perl version as indicated in $].
152           The second level hash is module => version pairs.
153
154           Note, it is possible for the version of a module to be unspecified,
155           whereby the value is "undef", so use "exists $version{$foo}{$bar}"
156           if that's what you're testing for.
157
158           Starting with 2.10, the special module name "Unicode" refers to the
159           version of the Unicode Character Database bundled with Perl.
160
161       %Module::CoreList::delta
162           Available in version 3.00 and above.
163
164           It is a hash of hashes that is keyed on perl version. Each keyed
165           hash will have the following keys:
166
167             delta_from - a previous perl version that the changes are based on
168             changed    - a hash of module/versions that have changed
169             removed    - a hash of modules that have been removed
170
171       %Module::CoreList::released
172           Keyed on perl version this contains ISO formatted versions of the
173           release dates, as gleaned from perlhist.
174
175       %Module::CoreList::families
176           New, in 1.96, a hash that clusters known perl releases by their
177           major versions.
178
179       %Module::CoreList::deprecated
180           A hash of hashes keyed on perl version and on module name.  If a
181           module is defined it indicates that that module is deprecated in
182           that perl version and is scheduled for removal from core at some
183           future point.
184
185       %Module::CoreList::upstream
186           A hash that contains information on where patches should be
187           directed for each core module.
188
189           UPSTREAM indicates where patches should go. "undef" implies that
190           this hasn't been discussed for the module at hand.  "blead"
191           indicates that the copy of the module in the blead sources is to be
192           considered canonical, "cpan" means that the module on CPAN is to be
193           patched first. "first-come" means that blead can be patched freely
194           if it is in sync with the latest release on CPAN.
195
196       %Module::CoreList::bug_tracker
197           A hash that contains information on the appropriate bug tracker for
198           each core module.
199
200           BUGS is an email or url to post bug reports.  For modules with
201           UPSTREAM => 'blead', use perl5-porters@perl.org.  rt.cpan.org
202           appears to automatically provide a URL for CPAN modules; any value
203           given here overrides the default:
204           http://rt.cpan.org/Public/Dist/Display.html?Name=$ModuleName
205

CAVEATS

207       Module::CoreList currently covers the 5.000, 5.001, 5.002, 5.003_07,
208       5.004, 5.004_05, 5.005, 5.005_03, 5.005_04 and 5.7.3 releases of perl.
209
210       All stable releases of perl since 5.6.0 are covered.
211
212       All development releases of perl since 5.9.0 are covered.
213

HISTORY

215       Moved to Changes file.
216

AUTHOR

218       Richard Clamp <richardc@unixbeard.net>
219
220       Currently maintained by the perl 5 porters <perl5-porters@perl.org>.
221

LICENSE

223       Copyright (C) 2002-2009 Richard Clamp.  All Rights Reserved.
224
225       This module is free software; you can redistribute it and/or modify it
226       under the same terms as Perl itself.
227