NAME

Distribution::Metadata - gather distribution metadata in local

SYNOPSIS

    use Distribution::Metadata;

    my $info = Distribution::Metadata->new_from_module("LWP::UserAgent");

    print $info->name;      # libwww-perl
    print $info->version;   # 6.13
    print $info->distvname; # libwww-perl-6.13
    print $info->author;    # ETHER
    print $info->pathname;  # E/ET/ETHER/libwww-perl-6.13.tar.gz

    print $info->main_module;         # LWP
    print $info->main_module_version; # 6.13
    print $info->main_module_file;    # path of LWP.pm

    print $info->packlist;       # path of .packlist
    print $info->meta_directory; # path of .meta directory
    print $info->install_json;   # path of install.json
    print $info->mymeta_json;    # path of MYMETA.json

    my $files = $info->files; # files which are listed in .packlist

    my $install_json_hash = $info->install_json_hash;
    my $mymeta_json_hash  = $info->mymeta_json_hash;

DESCRIPTION

(CAUTION: This module is still in development phase. API will change without notice.)

Sometimes we want to know: Where this module comes from? Which distribution does this module belong to?

Since cpanm 1.5000 (released 2011.10.13), it installs not only modules but also their meta data. So we can answer that questions!

Distribution::Metadata gathers distribution metadata in local. That is, this module tries to gather

• main module name, version, file

• .packlist file

• .meta directory

• install.json file

• MYMETA.json file

Please note that as mentioned above, this module deeply depends on cpanm behavior. If you install cpan modules by hands or some cpan clients other than cpanm, this module won't work.

HOW IT WORKS

Let me explain how $class->new_from_module($module, inc => $inc) works.

• Get $module_file by

      Module::Metadata->new_from_module($module, inc => $inc)->filename.

• Find $packlist in which $module_file is listed.

• From $packlist pathname (eg: ...auto/LWP/.packlist), determine $main_module and main module search directory $lib.

• Get $main_module_version by

      Module::Metadata->new_from_module($main_module, inc => [$lib, "$lib/$Config{archname}"])->version

• Find install.json that has "name" eq $main_module, and provides $main_module with version $main_module_version.

• Get .meta directory and MYMETA.json with install.json.

CONSTRUCTORS

my $info = $class->new_from_module($module, inc => \@dirs, fill_archlib => $bool)

Create Distribution::Metadata instance from module name.

You can append inc argument to specify module/packlist/meta search paths. Default is \@INC.

Also you can append fill_archlib argument so that archlibs are automatically added to inc if missing.

Please note that, even if the module cannot be found, new_from_module returns a Distribution::Metadata instance. However almost all methods returns false for such objects. If you want to know whether the distribution was found or not, try:

    my $info = $class->new_from_module($module);

    if ($info->packlist) {
        # found
    } else {
        # not found
    }

my $info = $class->new_from_file($file, inc => \@dirs, fill_archlib => $bool)

Create Distribution::Metadata instance from file path. You can append inc and fill_archlib arguments too.

Also new_from_file retunes a Distribution::Metadata instance, even if file cannot be found.

METHODS

Please note that the following methods return false when appropriate modules or files cannot be found.

my $name = $info->name (alias: $info->dist)

distribution name (eg: libwww-perl)

my $version = $info->version

distribution version (eg: 6.13)

my $distvname = $info->distvname

distribution vname (eg: libwww-perl-6.13)

my $author = $info->author (alias: $info->cpanid)

distribution author (eg: ETHER)

my $pathname = $info->pathname

distribution pathname (eg: E/ET/ETHER/libwww-perl-6.13.tar.gz)

my $file = $info->packlist

.packlist file path

my $dir = $info->meta_directory

.meta directory path

my $file = $info->install_json

install.json file path

my $file = $info->mymeta_json

MYMETA.json file path

my $main_module = $info->main_module

main module name

my $version = $info->main_module_version

main module version

my $file = $info->main_module_file

main module file path

my $files = $info->files

file paths which is listed in .packlist file, note that paths are acutually Cwd::abs_path()-ed

my $hash = $info->install_json_hash

a hash reference for install.json

    my $info = Distribution::Metadata->new_from_module("LWP::UserAgent");
    my $install = $info->install_json_hash;
    $install->{version};  # 6.13
    $install->{dist};     # libwww-perl-6.13
    $install->{provides}; # a hash reference of providing modules
    ...

my $hash = $info->mymeta_json_hash

a hash reference for MYMETA.json

    my $info = Distribution::Metadata->new_from_module("LWP::UserAgent");
    my $meta = $info->mymeta_hash;
    $meta->{version};  # 6.13
    $meta->{abstract}; # The World-Wide Web library for Perl
    $meta->{prereqs};  # prereq hash
    ...

SEE ALSO

Module::Metadata

App::cpanminus

LICENSE

Copyright (C) 2015 Shoichi Kaji

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Shoichi Kaji <skaji@cpan.org>