diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Module/CoreList.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Module/CoreList.pod | 251 |
1 files changed, 251 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Module/CoreList.pod b/Master/tlpkg/tlperl/lib/Module/CoreList.pod new file mode 100644 index 00000000000..edc00ec9feb --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Module/CoreList.pod @@ -0,0 +1,251 @@ +=head1 NAME + +Module::CoreList - what modules shipped with versions of perl + +=head1 SYNOPSIS + + use Module::CoreList; + + print $Module::CoreList::version{5.00503}{CPAN}; # prints 1.48 + + print Module::CoreList->first_release('File::Spec'); # prints 5.00405 + print Module::CoreList->first_release_by_date('File::Spec'); # prints 5.005 + print Module::CoreList->first_release('File::Spec', 0.82); # prints 5.006001 + + if (Module::CoreList::is_core('File::Spec')) { + print "File::Spec is a core module\n"; + } + + print join ', ', Module::CoreList->find_modules(qr/Data/); + # prints 'Data::Dumper' + print join ', ', + Module::CoreList->find_modules(qr/test::h.*::.*s/i, 5.008008); + # prints 'Test::Harness::Assert, Test::Harness::Straps' + + print join ", ", @{ $Module::CoreList::families{5.005} }; + # prints "5.005, 5.00503, 5.00504" + +=head1 DESCRIPTION + +Module::CoreList provides information on which core and dual-life modules shipped +with each version of L<perl>. + +It provides a number of mechanisms for querying this information. + +There is a utility called L<corelist> provided with this module +which is a convenient way of querying from the command-line. + +There is a functional programming API available for programmers to query +information. + +Programmers may also query the contained hash structures to find relevant +information. + +=head1 FUNCTIONS API + +These are the functions that are available, they may either be called as functions or class methods: + + Module::CoreList::first_release('File::Spec'); # as a function + + Module::CoreList->first_release('File::Spec'); # class method + +=over + +=item C<first_release( MODULE )> + +Behaviour since version 2.11 + +Requires a MODULE name as an argument, returns the perl version when that module first +appeared in core as ordered by perl version number or undef ( in scalar context ) +or an empty list ( in list context ) if that module is not in core. + +=item C<first_release_by_date( MODULE )> + +Requires a MODULE name as an argument, returns the perl version when that module first +appeared in core as ordered by release date or undef ( in scalar context ) +or an empty list ( in list context ) if that module is not in core. + +=item C<find_modules( REGEX, [ LIST OF PERLS ] )> + +Takes a regex as an argument, returns a list of modules that match the regex given. +If only a regex is provided applies to all modules in all perl versions. Optionally +you may provide a list of perl versions to limit the regex search. + +=item C<find_version( PERL_VERSION )> + +Takes a perl version as an argument. Returns that perl version if it exists or C<undef> +otherwise. + +=item C<is_core( MODULE, [ MODULE_VERSION, [ PERL_VERSION ] ] )> + +Available in version 2.99 and above. + +Returns true if MODULE was bundled with the specified version of Perl. +You can optionally specify a minimum version of the module, +and can also specify a version of Perl. +If a version of Perl isn't specified, +C<is_core()> will use the numeric version of Perl that is running (ie C<$]>). + +If you want to specify the version of Perl, but don't care about +the version of the module, pass C<undef> for the module version: + +=item C<is_deprecated( MODULE, PERL_VERSION )> + +Available in version 2.22 and above. + +Returns true if MODULE is marked as deprecated in PERL_VERSION. If PERL_VERSION is +omitted, it defaults to the current version of Perl. + +=item C<deprecated_in( MODULE )> + +Available in version 2.77 and above. + +Returns the first PERL_VERSION where the MODULE was marked as deprecated. Returns C<undef> +if the MODULE has not been marked as deprecated. + +=item C<removed_from( MODULE )> + +Available in version 2.32 and above + +Takes a module name as an argument, returns the first perl version where that module +was removed from core. Returns undef if the given module was never in core or remains +in core. + +=item C<removed_from_by_date( MODULE )> + +Available in version 2.32 and above + +Takes a module name as an argument, returns the first perl version by release date where that module +was removed from core. Returns undef if the given module was never in core or remains +in core. + +=item C<changes_between( PERL_VERSION, PERL_VERSION )> + +Available in version 2.66 and above. + +Given two perl versions, this returns a list of pairs describing the changes in +core module content between them. The list is suitable for storing in a hash. +The keys are library names and the values are hashrefs. Each hashref has an +entry for one or both of C<left> and C<right>, giving the versions of the +library in each of the left and right perl distributions. + +For example, it might return these data (among others) for the difference +between 5.008000 and 5.008001: + + 'Pod::ParseLink' => { left => '1.05', right => '1.06' }, + 'Pod::ParseUtils' => { left => '0.22', right => '0.3' }, + 'Pod::Perldoc' => { right => '3.10' }, + 'Pod::Perldoc::BaseTo' => { right => undef }, + +This shows us two libraries being updated and two being added, one of which has +an undefined version in the right-hand side version. + +=back + +=head1 DATA STRUCTURES + +These are the hash data structures that are available: + +=over + +=item C<%Module::CoreList::version> + +A hash of hashes that is keyed on perl version as indicated +in $]. The second level hash is module => version pairs. + +Note, it is possible for the version of a module to be unspecified, +whereby the value is C<undef>, so use C<exists $version{$foo}{$bar}> if +that's what you're testing for. + +Starting with 2.10, the special module name C<Unicode> refers to the version of +the Unicode Character Database bundled with Perl. + +=item C<%Module::CoreList::delta> + +Available in version 3.00 and above. + +C<%Module::CoreList::version> is implemented via C<Module::CoreList::TieHashDelta> +using this hash of delta changes. + +It is a hash of hashes that is keyed on perl version. Each keyed hash will have the +following keys: + + delta_from - a previous perl version that the changes are based on + changed - a hash of module/versions that have changed + removed - a hash of modules that have been removed + +=item C<%Module::CoreList::released> + +Keyed on perl version this contains ISO +formatted versions of the release dates, as gleaned from L<perlhist>. + +=item C<%Module::CoreList::families> + +New, in 1.96, a hash that +clusters known perl releases by their major versions. + +=item C<%Module::CoreList::deprecated> + +A hash of hashes keyed on perl version and on module name. +If a module is defined it indicates that that module is +deprecated in that perl version and is scheduled for removal +from core at some future point. + +=item C<%Module::CoreList::upstream> + +A hash that contains information on where patches should be directed +for each core module. + +UPSTREAM indicates where patches should go. C<undef> implies +that this hasn't been discussed for the module at hand. +C<blead> indicates that the copy of the module in the blead +sources is to be considered canonical, C<cpan> means that the +module on CPAN is to be patched first. C<first-come> means +that blead can be patched freely if it is in sync with the +latest release on CPAN. + +=item C<%Module::CoreList::bug_tracker> + +A hash that contains information on the appropriate bug tracker +for each core module. + +BUGS is an email or url to post bug reports. For modules with +UPSTREAM => 'blead', use perl5-porters@perl.org. rt.cpan.org +appears to automatically provide a URL for CPAN modules; any value +given here overrides the default: +http://rt.cpan.org/Public/Dist/Display.html?Name=$ModuleName + +=back + +=head1 CAVEATS + +Module::CoreList currently covers the 5.000, 5.001, 5.002, 5.003_07, +5.004, 5.004_05, 5.005, 5.005_03, 5.005_04 and 5.7.3 releases of perl. + +All stable releases of perl since 5.6.0 are covered. + +All development releases of perl since 5.9.0 are covered. + + +=head1 HISTORY + +Moved to Changes file. + +=head1 AUTHOR + +Richard Clamp E<lt>richardc@unixbeard.netE<gt> + +Currently maintained by the perl 5 porters E<lt>perl5-porters@perl.orgE<gt>. + +=head1 LICENSE + +Copyright (C) 2002-2009 Richard Clamp. All Rights Reserved. + +This module is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. + +=head1 SEE ALSO + +L<corelist>, L<Module::Info>, L<perl>, L<http://perlpunks.de/corelist> + +=cut |