[![Build Status](https://travis-ci.org/shoichikaji/Distribution-Metadata.svg?branch=master)](https://travis-ci.org/shoichikaji/Distribution-Metadata) # 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](https://metacpan.org/pod/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 - `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](https://metacpan.org/pod/Module::Metadata) [App::cpanminus](https://metacpan.org/pod/App::cpanminus) # LICENSE Copyright (C) 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