[perl5.git] / dist / Module-CoreList / corelist

#!/usr/bin/perl

=head1 NAME

corelist - a commandline frontend to Module::CoreList

=head1 DESCRIPTION

See L<Module::CoreList> for one.

=head1 SYNOPSIS

    corelist -v
    corelist [-a|-d] <ModuleName> | /<ModuleRegex>/ [<ModuleVersion>] ...
    corelist [-v <PerlVersion>] [ <ModuleName> | /<ModuleRegex>/ ] ...

=head1 OPTIONS

=over

=item -a

lists all versions of the given module (or the matching modules, in case you
used a module regexp) in the perls Module::CoreList knows about.

    corelist -a utf8

    utf8 was first released with perl 5.006
      5.006      undef
      5.006001   undef
      5.006002   undef
      5.007003   1.00
      5.008      1.00
      5.008001   1.02
      5.008002   1.02
      5.008003   1.02
      5.008004   1.03
      5.008005   1.04
      5.008006   1.04
      5.008007   1.05
      5.008008   1.06
      5.009      1.02
      5.009001   1.02
      5.009002   1.04
      5.009003   1.06

=item -d

finds the first perl version where a module has been released by
date, and not by version number (as is the default).

=item -? or -help

help! help! help! to see more help, try --man.

=item -man

all of the help

=item -v

lists all of the perl release versions we got the CoreList for.

If you pass a version argument (value of C<$]>, like C<5.00503> or C<5.008008>),
you get a list of all the modules and their respective versions.
(If you have the C<version> module, you can also use new-style version numbers,
like C<5.8.8>.)

In module filtering context, it can be used as Perl version filter.

=back

As a special case, if you specify the module name C<Unicode>, you'll get
the version number of the Unicode Character Database bundled with the
requested perl versions.

=cut

use Module::CoreList;
use Getopt::Long;
use Pod::Usage;
use strict;
use warnings;

my %Opts;

GetOptions(\%Opts, qw[ help|?! man! v|version:f a! d ] );

pod2usage(1) if $Opts{help};
pod2usage(-verbose=>2) if $Opts{man};

if(exists $Opts{v} ){
    if( !$Opts{v} ) {
        print "\nModule::CoreList has info on the following perl versions:\n";
        print "$_\n" for sort keys %Module::CoreList::version;
        print "\n";
        exit 0;
    }

    $Opts{v} = numify_version( $Opts{v} );
    my $version_hash = Module::CoreList->find_version($Opts{v});
    if( !$version_hash ) {
        print "\nModule::CoreList has no info on perl v$Opts{v}\n\n";
        exit 1;
    }

    if ( !@ARGV ) {
	print "\nThe following modules were in perl v$Opts{v} CORE\n";
	print "$_ ", $version_hash->{$_} || " ","\n"
	for sort keys %$version_hash;
	print "\n";
	exit 0;
    }
}

if ( !@ARGV ) {
    pod2usage(0);
}

while (@ARGV) {
	my ($mod, $ver);
	if ($ARGV[0] =~ /=/) {
	    ($mod, $ver) = split /=/, shift @ARGV;
	} else {
	    $mod = shift @ARGV;
	    $ver = (@ARGV && $ARGV[0] =~ /^\d/) ? shift @ARGV : "";
	}

	if ($mod !~ m|^/(.*)/([imosx]*)$|) { # not a regex
	    module_version($mod,$ver);
	} else {
	    my $re;
	    eval { $re = $2 ? qr/(?$2)($1)/ : qr/$1/; }; # trap exceptions while building regex
	    if ($@) {
		# regex errors are usually like 'Quantifier follow nothing in regex; marked by ...'
		# then we drop text after ';' to shorten message
		my $errmsg = $@ =~ /(.*);/ ? $1 : $@;
		warn "\n$mod  is a bad regex: $errmsg\n";
		next;
	    }
	    my @mod = Module::CoreList->find_modules($re);
	    if (@mod) {
		module_version($_, $ver) for @mod;
	    } else {
		$ver |= '';
		print "\n$mod $ver has no match in CORE (or so I think)\n";
	    }

	}
}

exit();

sub module_version {
    my($mod,$ver) = @_;

    if ( $Opts{v} ) {
	my $version_hash = Module::CoreList->find_version($Opts{v});
	if ($version_hash) {
	    print $mod, " ", $version_hash->{$mod} || 'undef', "\n";
	    return;
	}
	else { die "Shouldn't happen" }
    }

    my $ret = $Opts{d}
	? Module::CoreList->first_release_by_date(@_)
	: Module::CoreList->first_release(@_);
    my $msg = $mod;
    $msg .= " $ver" if $ver;

    if( defined $ret ) {
        $msg .= " was ";
        $msg .= "first " unless $ver;
        $msg .= "released with perl $ret"
    } else {
        $msg .= " was not in CORE (or so I think)";
    }

    print "\n",$msg,"\n";

    if(defined $ret and exists $Opts{a} and $Opts{a}){
        for my $v(
            sort keys %Module::CoreList::version ){

            printf "  %-10s %-10s\n",
                $v,
                $Module::CoreList::version{$v}{$mod}
                    || 'undef'
                    if exists $Module::CoreList::version{$v}{$mod};
        }
        print "\n";
    }
}

sub numify_version {
    my $ver = shift;
    if ($ver =~ /\..+\./) {
	eval { require version ; 1 }
	    or die "You need to install version.pm to use dotted version numbers\n";
        $ver = version->new($ver)->numify;
    }
    $ver += 0;
    return $ver;
}

=head1 EXAMPLES

    $ corelist File::Spec

    File::Spec was first released with perl 5.005

    $ corelist File::Spec 0.83

    File::Spec 0.83 was released with perl 5.007003

    $ corelist File::Spec 0.89

    File::Spec 0.89 was not in CORE (or so I think)

    $ corelist File::Spec::Aliens

    File::Spec::Aliens  was not in CORE (or so I think)

    $ corelist /IPC::Open/

    IPC::Open2 was first released with perl 5

    IPC::Open3 was first released with perl 5

    $ corelist /MANIFEST/i

    ExtUtils::Manifest was first released with perl 5.001

    $ corelist /Template/

    /Template/  has no match in CORE (or so I think)

    $ corelist -v 5.8.8 B

    B                        1.09_01

    $ corelist -v 5.8.8 /^B::/

    B::Asmdata               1.01
    B::Assembler             0.07
    B::Bblock                1.02_01
    B::Bytecode              1.01_01
    B::C                     1.04_01
    B::CC                    1.00_01
    B::Concise               0.66
    B::Debug                 1.02_01
    B::Deparse               0.71
    B::Disassembler          1.05
    B::Lint                  1.03
    B::O                     1.00
    B::Showlex               1.02
    B::Stackobj              1.00
    B::Stash                 1.00
    B::Terse                 1.03_01
    B::Xref                  1.01

=head1 COPYRIGHT

Copyright (c) 2002-2007 by D.H. aka PodMaster

Currently maintained by the perl 5 porters E<lt>perl5-porters@perl.orgE<gt>.

This program is distributed under the same terms as perl itself.
See http://perl.org/ or http://cpan.org/ for more info on that.

=cut
Commit	Line	Data
aee92da2	1	#!/usr/bin/perl
8f2fd531 JB	2
	3	=head1 NAME
	4
	5	corelist - a commandline frontend to Module::CoreList
	6
	7	=head1 DESCRIPTION
	8
	9	See L<Module::CoreList> for one.
	10
	11	=head1 SYNOPSIS
	12
87fbace9	13	corelist -v
6127f3cd	14	corelist [-a\|-d] <ModuleName> \| /<ModuleRegex>/ [<ModuleVersion>] ...
87fbace9	15	corelist [-v <PerlVersion>] [ <ModuleName> \| /<ModuleRegex>/ ] ...
8f2fd531 JB	16
	17	=head1 OPTIONS
	18
567f8e5b RGS	19	=over
567f8e5b RGS	20
6127f3cd	21	=item -a
8f2fd531	22
87fbace9 RGS	23	lists all versions of the given module (or the matching modules, in case you
	24	used a module regexp) in the perls Module::CoreList knows about.
	25
8f2fd531 JB	26	corelist -a utf8
8f2fd531 JB	27
f9cff7e6	28	utf8 was first released with perl 5.006
8f2fd531 JB	29	5.006 undef
	30	5.006001 undef
	31	5.006002 undef
	32	5.007003 1.00
	33	5.008 1.00
	34	5.008001 1.02
	35	5.008002 1.02
	36	5.008003 1.02
	37	5.008004 1.03
	38	5.008005 1.04
	39	5.008006 1.04
f372d768 RGS	40	5.008007 1.05
f372d768 RGS	41	5.008008 1.06
8f2fd531 JB	42	5.009 1.02
8f2fd531 JB	43	5.009001 1.02
567f8e5b	44	5.009002 1.04
f372d768	45	5.009003 1.06
8f2fd531	46
6127f3cd RGS	47	=item -d
	48
	49	finds the first perl version where a module has been released by
	50	date, and not by version number (as is the default).
	51
aee92da2	52	=item -? or -help
8f2fd531 JB	53
	54	help! help! help! to see more help, try --man.
	55
567f8e5b	56	=item -man
8f2fd531 JB	57
	58	all of the help
	59
567f8e5b	60	=item -v
8f2fd531 JB	61
	62	lists all of the perl release versions we got the CoreList for.
	63
87fbace9	64	If you pass a version argument (value of C<$]>, like C<5.00503> or C<5.008008>),
8f2fd531	65	you get a list of all the modules and their respective versions.
87fbace9 RGS	66	(If you have the C<version> module, you can also use new-style version numbers,
87fbace9 RGS	67	like C<5.8.8>.)
8f2fd531	68
0cecb811 RGS	69	In module filtering context, it can be used as Perl version filter.
0cecb811 RGS	70
567f8e5b	71	=back
8f2fd531	72
6f00ef79 RGS	73	As a special case, if you specify the module name C<Unicode>, you'll get
	74	the version number of the Unicode Character Database bundled with the
	75	requested perl versions.
	76
8f2fd531 JB	77	=cut
	78
	79	use Module::CoreList;
	80	use Getopt::Long;
	81	use Pod::Usage;
	82	use strict;
aee92da2	83	use warnings;
8f2fd531 JB	84
	85	my %Opts;
	86
6127f3cd	87	GetOptions(\%Opts, qw[ help\|?! man! v\|version:f a! d ] );
8f2fd531 JB	88
	89	pod2usage(1) if $Opts{help};
	90	pod2usage(-verbose=>2) if $Opts{man};
	91
	92	if(exists $Opts{v} ){
0cecb811	93	if( !$Opts{v} ) {
b69ffb0c	94	print "\nModule::CoreList has info on the following perl versions:\n";
8f2fd531 JB	95	print "$_\n" for sort keys %Module::CoreList::version;
8f2fd531 JB	96	print "\n";
0cecb811 RGS	97	exit 0;
	98	}
	99
	100	$Opts{v} = numify_version( $Opts{v} );
6127f3cd RGS	101	my $version_hash = Module::CoreList->find_version($Opts{v});
6127f3cd RGS	102	if( !$version_hash ) {
0cecb811 RGS	103	print "\nModule::CoreList has no info on perl v$Opts{v}\n\n";
0cecb811 RGS	104	exit 1;
8f2fd531	105	}
0cecb811 RGS	106
	107	if ( !@ARGV ) {
	108	print "\nThe following modules were in perl v$Opts{v} CORE\n";
6127f3cd RGS	109	print "$_ ", $version_hash->{$_} \|\| " ","\n"
6127f3cd RGS	110	for sort keys %$version_hash;
0cecb811 RGS	111	print "\n";
	112	exit 0;
	113	}
	114	}
	115
	116	if ( !@ARGV ) {
	117	pod2usage(0);
	118	}
	119
	120	while (@ARGV) {
567f8e5b RGS	121	my ($mod, $ver);
	122	if ($ARGV[0] =~ /=/) {
	123	($mod, $ver) = split /=/, shift @ARGV;
	124	} else {
	125	$mod = shift @ARGV;
	126	$ver = (@ARGV && $ARGV[0] =~ /^\d/) ? shift @ARGV : "";
	127	}
18b19aec RGS	128
	129	if ($mod !~ m\|^/(.)/([imosx])$\|) { # not a regex
	130	module_version($mod,$ver);
	131	} else {
	132	my $re;
	133	eval { $re = $2 ? qr/(?$2)($1)/ : qr/$1/; }; # trap exceptions while building regex
	134	if ($@) {
	135	# regex errors are usually like 'Quantifier follow nothing in regex; marked by ...'
	136	# then we drop text after ';' to shorten message
	137	my $errmsg = $@ =~ /(.*);/ ? $1 : $@;
	138	warn "\n$mod is a bad regex: $errmsg\n";
	139	next;
	140	}
	141	my @mod = Module::CoreList->find_modules($re);
	142	if (@mod) {
	143	module_version($_, $ver) for @mod;
	144	} else {
	145	$ver \|= '';
	146	print "\n$mod $ver has no match in CORE (or so I think)\n";
	147	}
	148
	149	}
8f2fd531 JB	150	}
	151
	152	exit();
	153
	154	sub module_version {
	155	my($mod,$ver) = @_;
	156
0cecb811	157	if ( $Opts{v} ) {
6127f3cd RGS	158	my $version_hash = Module::CoreList->find_version($Opts{v});
	159	if ($version_hash) {
	160	print $mod, " ", $version_hash->{$mod} \|\| 'undef', "\n";
	161	return;
	162	}
	163	else { die "Shouldn't happen" }
0cecb811 RGS	164	}
0cecb811 RGS	165
6127f3cd RGS	166	my $ret = $Opts{d}
	167	? Module::CoreList->first_release_by_date(@_)
	168	: Module::CoreList->first_release(@_);
f9cff7e6 RGS	169	my $msg = $mod;
f9cff7e6 RGS	170	$msg .= " $ver" if $ver;
8f2fd531 JB	171
	172	if( defined $ret ) {
	173	$msg .= " was ";
	174	$msg .= "first " unless $ver;
	175	$msg .= "released with perl $ret"
	176	} else {
	177	$msg .= " was not in CORE (or so I think)";
	178	}
	179
	180	print "\n",$msg,"\n";
567f8e5b	181
8f2fd531 JB	182	if(defined $ret and exists $Opts{a} and $Opts{a}){
8f2fd531 JB	183	for my $v(
8f2fd531 JB	184	sort keys %Module::CoreList::version ){
	185
	186	printf " %-10s %-10s\n",
	187	$v,
	188	$Module::CoreList::version{$v}{$mod}
	189	\|\| 'undef'
	190	if exists $Module::CoreList::version{$v}{$mod};
	191	}
	192	print "\n";
	193	}
	194	}
	195
0cecb811 RGS	196	sub numify_version {
0cecb811 RGS	197	my $ver = shift;
6127f3cd RGS	198	if ($ver =~ /\..+\./) {
	199	eval { require version ; 1 }
	200	or die "You need to install version.pm to use dotted version numbers\n";
0cecb811 RGS	201	$ver = version->new($ver)->numify;
0cecb811 RGS	202	}
6127f3cd	203	$ver += 0;
0cecb811 RGS	204	return $ver;
0cecb811 RGS	205	}
8f2fd531 JB	206
	207	=head1 EXAMPLES
	208
	209	$ corelist File::Spec
	210
f9cff7e6	211	File::Spec was first released with perl 5.005
8f2fd531 JB	212
	213	$ corelist File::Spec 0.83
	214
	215	File::Spec 0.83 was released with perl 5.007003
	216
	217	$ corelist File::Spec 0.89
	218
	219	File::Spec 0.89 was not in CORE (or so I think)
	220
	221	$ corelist File::Spec::Aliens
	222
	223	File::Spec::Aliens was not in CORE (or so I think)
	224
18b19aec RGS	225	$ corelist /IPC::Open/
18b19aec RGS	226
f9cff7e6	227	IPC::Open2 was first released with perl 5
18b19aec	228
f9cff7e6	229	IPC::Open3 was first released with perl 5
18b19aec RGS	230
	231	$ corelist /MANIFEST/i
	232
f9cff7e6	233	ExtUtils::Manifest was first released with perl 5.001
18b19aec RGS	234
	235	$ corelist /Template/
	236
	237	/Template/ has no match in CORE (or so I think)
	238
0cecb811 RGS	239	$ corelist -v 5.8.8 B
	240
	241	B 1.09_01
	242
	243	$ corelist -v 5.8.8 /^B::/
	244
	245	B::Asmdata 1.01
	246	B::Assembler 0.07
	247	B::Bblock 1.02_01
	248	B::Bytecode 1.01_01
	249	B::C 1.04_01
	250	B::CC 1.00_01
	251	B::Concise 0.66
	252	B::Debug 1.02_01
	253	B::Deparse 0.71
	254	B::Disassembler 1.05
	255	B::Lint 1.03
	256	B::O 1.00
	257	B::Showlex 1.02
	258	B::Stackobj 1.00
	259	B::Stash 1.00
	260	B::Terse 1.03_01
	261	B::Xref 1.01
18b19aec	262
8f2fd531 JB	263	=head1 COPYRIGHT
8f2fd531 JB	264
6f00ef79	265	Copyright (c) 2002-2007 by D.H. aka PodMaster
567f8e5b	266
6f00ef79	267	Currently maintained by the perl 5 porters E<lt>perl5-porters@perl.orgE<gt>.
8f2fd531 JB	268
8f2fd531 JB	269	This program is distributed under the same terms as perl itself.
f372d768	270	See http://perl.org/ or http://cpan.org/ for more info on that.
8f2fd531 JB	271
8f2fd531 JB	272	=cut