summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Module/CoreList.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Module/CoreList.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Module/CoreList.pod251
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