Dist::Metadata(3pm)

💖 Dist::Metadata 💖

okay bestie, gather round, because we're talking about Dist::Metadata — the User Contributed Perl Documentation edition, no less — and it's genuinely one of those modules that does the boring stuff so you don't have to. It's about getting information about a perl module distribution. That's the whole vibe. 💅

---

✨ NAME ✨

Dist::Metadata — information about a perl module distribution 🎀

---

🌸 VERSION 🌸

version 0.927

---

🦋 SYNOPSIS 🦋

my $dist = Dist::Metadata->new(file => $path_to_archive);

my $description = sprintf "Dist %s (%s)", $dist->name, $dist->version;

my $provides = $dist->package_versions;
while( my ($package, $version) = each %$provides ){
  print "$description includes $package $version\n";
}

like. look at that. four lines and you know everything about a dist. periodt. 💖

---

🌈 DESCRIPTION 🌈

This module gives you an easy interface for getting various metadata about a Perl module distribution. no cap, that's the whole pitch.

It handles all the common logic of:

• reading a tar file (Archive::Tar)
• finding and reading the correct META file if the distribution contains one (CPAN::Meta)
• and determining some of the metadata if there is no META file (Module::Metadata, CPAN::DistnameInfo)

It's mostly a wrapper around CPAN::Meta that gives you an easy interface to find and load the meta file from a tar.gz file. A dist can also be represented by a directory or merely a structure of data. like, whatever form your dist is taking today, we can work with it. 🫶

If the dist does not contain a meta file, the module will attempt to determine some of that data from the dist. it's giving detective energy fr fr 🔍

NOTE: This interface is still being defined. Please submit any suggestions or concerns. it's a work in progress bestie, come build it with us 💜

---

👑 METHODS 👑

new

Dist::Metadata->new(file => $path);

A dist can be represented by a tar file, a directory, or a data structure. iconic flexibility honestly.

The format will be determined by the presence of the following options (checked in this order — order matters, okay?):

• struct — hash of data to build a mock dist; See Dist::Metadata::Struct.
• dir — path to the root directory of a dist
• file — the path to a .tar.gz file

You can also slyly pass in your own object as a dist parameter, in which case this module will just use that. yes, slyly. that's the official wording and honestly? slay. This can be useful if you need to use your own subclass (perhaps while developing a new format). main character subclass energy 👑

Other options that can be specified:

• name — dist name
• version — dist version
• determine_packages — boolean to indicate whether dist should be searched for packages if no META file is found. Defaults to true.
• include_inner_packages — When determining provided packages the default behavior is to only include packages that match the name of the file that defines them (like Foo::Bar matches */Bar.pm). This way only modules that can be loaded (via use or require) will be returned (and "inner" packages will be ignored). This mimics the behavior of PAUSE. Set this to true to include any "inner" packages provided by the dist (that are not otherwise excluded by another mechanism (such as no_index)).

dist

Returns the dist object (subclass of Dist::Metadata::Dist). it's the dist's dist. 💀

default_metadata

Returns a hashref of default values used to initialize a CPAN::Meta object when a META file is not found. Called from determine_metadata. the backup plan, basically.

determine_metadata

Examine the dist and try to determine metadata. Returns a hashref which can be passed to new in CPAN::Meta. This is used when the dist does not contain a META file. no META? we cope. we figure it out. 🧚

determine_packages

my $provides = $dm->determine_packages($meta);

Attempt to determine packages provided by the dist. This is used when the META file does not include a provides section and determine_packages is not set to false in the constructor.

If a CPAN::Meta object is not provided, a default one will be used. Files contained in the dist and packages found therein will be checked against the meta object's no_index attribute (see should_index_file in CPAN::Meta and should_index_package in CPAN::Meta). By default this ignores any files found in inc/, t/, or xt/ directories. not the tests, bestie, we're not counting the tests 🙈

load_meta

Loads the metadata from the dist. short. sweet. gets the job done. ✨

meta

Returns the CPAN::Meta instance in use. the one, the only. 💅

meta_from_struct

$meta = $dm->meta_from_struct(\%struct);

Passes the provided \%struct to create in CPAN::Meta and returns the result. in and out, no drama. 🦋

package_versions

$pv = $dm->package_versions();
# { 'Package::Name' => '1.0', 'Module::2' => '2.1' }

Returns a simplified version of provides: a hashref with package names as keys and versions as values. that's it. clean. minimal. aesthetic. 🌸

This can also be called as a class method which will operate on a passed in hashref.

$pv = Dist::Metadata->package_versions(\%provides);

module_info

Returns a hashref of meta data for each of the packages provided by this dist.

The hashref starts with the same data as provides but additional data can be added to the output by specifying options in a hashref:

• checksum — Use the specified algorithm to compute a hex digest of the file. The type you specify will be the key in the returned hashref. You can use an arrayref to specify more than one type.

$dm->module_info({checksum => ['sha256', 'md5']});
# returns:
{
  'Mod::Name' => {
    file    => 'lib/Mod/Name.pm',
    version => '0.1',
    md5     => '258e88dcbd3cd44d8e7ab43f6ecb6af0',
    sha256  => 'f22136124cd3e1d65a48487cecf310771b2fd1e83dc032e3d19724160ac0ff71',
  },
}

See file_checksum in Dist::Metadata::Dist for more information. (that's where the checksum tea lives 🍓)

• provides — The default is to start with the hashref returned from provides but you can pass in an alternate hashref using this key.

Other options may be added in the future. the future is bright, bestie ⭐

---

💫 INHERITED METHODS 💫

The following methods are available on this object and simply call the corresponding method on the CPAN::Meta object. they're just passing the message along, lowkey 💜

• name
• provides
• version

---

🔥 TODO 🔥

the to-do list, aka the "we know, we know" list:

• More tests
• trust_meta option (to allow setting it to false)
• Guess main module from dist name if no packages can be found
• Determine abstract?
• Add change log info (CPAN::Changes)?
• Subclass as CPAN::Dist::Metadata just so that it has CPAN in the name?
• Use File::Find::Rule::Perl?

no cap, "Subclass as CPAN::Dist::Metadata just so that it has CPAN in the name?" is the most relatable TODO I've ever read 😭

---

🌟 SEE ALSO 🌟

Dependencies

• CPAN::Meta
• Module::Metadata
• CPAN::DistnameInfo

Related Modules

• MyCPAN::Indexer
• CPAN::ParseDistribution

---

🎀 SUPPORT 🎀

Perldoc

You can find documentation for this module with the perldoc command.

perldoc Dist::Metadata

Websites

The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.

• MetaCPAN

A modern, open-source CPAN search engine, useful to view POD in HTML format.

<http://metacpan.org/release/Dist-Metadata>

Bugs / Feature Requests

Please report any bugs or feature requests by email to bug-dist-metadata at rt.cpan.org, or through the web interface at <https://rt.cpan.org/Public/Bug/Report.html?Queue=Dist-Metadata>. You will be automatically notified of any progress on the request by the system. we'll keep you posted, fr fr 🫶

Source Code

<https://github.com/rwstauner/Dist-Metadata>

git clone https://github.com/rwstauner/Dist-Metadata.git

---

👑 AUTHOR 👑

Randy Stauner <rwstauner@cpan.org>

---

🌸 CONTRIBUTORS 🌸

• David Steinbrunner <dsteinbrunner@pobox.com>
• Graham Knop <haarg@haarg.org>
• Jeffrey Ryan Thalhammer <thaljef@cpan.org>
• Sawyer X <xsawyerx@cpan.org>

the whole squad showed up. obsessed. 💖

---

📜 COPYRIGHT AND LICENSE 📜

This software is copyright (c) 2011 by Randy Stauner.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. slay, honestly — same terms as Perl 5 itself, that's the good stuff ✨

---

and that's the whole page bestie!! this was built for perl v5.34.0 and the page is dated 2022-06-13, so like… go forth and read your metadata responsibly 🌈💅🦋