Dist::...ackage(3pm)

🦋 Dist::Zilla::Plugin::MetaProvides::Package — the manual, but make it cute

okay bestie, you're reading the page for Dist::Zilla::Plugin::MetaProvides::Package(3pm) and honestly? it's giving "quietly essential plugin" energy. it's part of the User Contributed Perl Documentation crew. let's get into it 💖

---

✨ VERSION ✨

version 2.004003 — she's at 2.004003, periodt.

---

🌸 SYNOPSIS 🌸

so in your dist.ini you do this:

[MetaProvides::Package]

; This is the (optional) default: This forces any package versions
; added in the "provides" metadata to use the 'version'
; specified by dzil.
;
; Set it to 0 to force packages own versions to be respected. ( You probably don't want this )
inherit_version = 1

; This is also the (optional) default: This forces any package without
; a version declaration to use the 'version' specified by default.
;
; Set it to 0 to allow packages to have no versions
inherit_missing = 1

; This is the (optional) default: This being true discovers any [MetaNoIndex]
; plugins to also further exclude packages from the provides map.
;
; Set it to 0 if for some weird reason you don't want this.
meta_noindex    = 1

; This is the (optional) default: Packages named _Foo::Bar or Foo::_Bar are not indexed.
; Set this to 1 to enable indexing of similarly named packages.
include_underscores = 0

yes, every single one of those is the optional default, and yes, the comments are doing the heavy lifting. iykyk 🎀

---

💜 DESCRIPTION 💜

so like, this is a Dist::Zilla plugin, right? and what it does is it populates the provides property of META.json and META.yml by absorbing it from your shipped modules — and it does that in a manner similar to how PAUSE itself does it. matching energy fr fr.

why do you care? because this lets you easily create an authoritative index of what module provides what version in advance of PAUSE indexing it — and PAUSE will then take that verbatim. no cap. that's the whole point. 🔥

---

👑 CONSUMED ROLES 👑

Dist::Zilla::Role::MetaProvider::Provider

---

⭐ ROLE SATISFYING METHODS ⭐

provides

a conformant function to the Dist::Zilla::Role::MetaProvider::Provider Role. she conforms. that's her job. 💅

signature: $plugin->provides()

returns: Array of Dist::Zilla::MetaProvides::ProvideRecord

---

🎀 ATTRIBUTES 🎀

include_underscores

this attribute is the one controlling the automatic skipping of packages.

by default, MetaProvides::Package skips packages matching this regular expression:

qr/(\A|::)_/

set this attribute to a "true" value and we stop skipping those packages. letting the underscore-named ones through. bold move, iconic.

this feature was added in "2.004001-TRIAL" — so if you're on something older, she's not there yet, sorry bestie 😭

finder

this attribute, if you specify it, will:

• Override the FileFinder used to find files containing packages
• Inhibit autovivification of the .pm file finder

this parameter may be specified multiple times to aggregate a list of finders. yes, multiple. stack 'em up. 🫶

---

🌈 OPTIONS INHERITED FROM Dist::Zilla::Role::MetaProvider::Provider 🌈

inherit_version

okay so the big question: how do you want existing versions — meaning versions hard-coded into files before running this plug-in — to be processed? two moods:

• DEFAULT: inherit_version = 1 — ignore anything you find in a file, and just probe DZIL->version() for a value. this is a sane default and most will want this. sane. default. periodt.
• inherit_version = 0 — use this option if you actually want to use hard-coded values in your files and use the versions parsed out of them.

inherit_missing

in the event you are using the aforementioned "inherit_version" = 0, this determines how to behave when encountering a module with no version defined.

• DEFAULT: inherit_missing = 1 — when a module has no version, probe DZIL->version() for an answer. this is what you want if you want to have some files with fixed versions, and others to just automatically be maintained by Dist::Zilla. hybrid queen ✨
• inherit_missing = 0 — when a module has no version, emit a versionless record in the final metadata.

meta_noindex

this is a utility for people who are also using MetaNoIndex, so that its settings can be used to eliminate items from the 'provides' list. teamwork!

• meta_noindex = 0 — with this set, any MetaNoIndex plugins are ignored.
• DEFAULT: meta_noindex = 1 — when a module meets the criteria provided to MetaNoIndex, eliminate it from the metadata shipped to Dist::Zilla. bye bye 👋

---

💖 SEE ALSO 💖

• Dist::Zilla::Plugin::MetaProvides

---

🌼 AUTHOR 🌼

Kent Fredric <kentnl@cpan.org>

---

🍓 COPYRIGHT AND LICENSE 🍓

This software is copyright (c) 2017 by Kent Fredric <kentfredric@gmail.com>.

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, and also legally binding in the chillest way possible 💅

---

and that's the whole page bestie!! 🫶 generated with perl v5.36.0 and dated 2022-08-28, so if your docs are older than that... go update, i'm literally begging 🙈💖