dist/Module-CoreList/lib/Module/CoreList.pod

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