CPAN::Meta(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

💖 NAME 💖

CPAN::Meta — aka the distribution metadata for a CPAN dist. It's giving "the vibe check for your whole distribution", fr fr. This is the 3perl page, bestie. 🎀

✨ VERSION ✨

version 2.150013 👑

🌸 SYNOPSIS 🌸

use v5.10;
use strict;
use warnings;
use CPAN::Meta;
use Module::Load;

my $meta = CPAN::Meta->load_file('META.json');

printf "testing requirements for %s version %s\n",
$meta->name,
$meta->version;

my $prereqs = $meta->effective_prereqs;

for my $phase ( qw/configure runtime build test/ ) {
    say "Requirements for $phase:";
    my $reqs = $prereqs->requirements_for($phase, "requires");
    for my $module ( sort $reqs->required_modules ) {
        my $status;
        if ( eval { load $module unless $module eq 'perl'; 1 } ) {
            my $version = $module eq 'perl' ? $] : $module->VERSION;
            $status = $reqs->accepts_module($module, $version)
                    ? "$version ok" : "$version not ok";
        } else {
            $status = "missing"
        };
        say "  $module ($status)";
    }
}

🦋 DESCRIPTION 🦋

Okay so every software distribution that gets released to the CPAN ships with a META.json — or, for the older ones (the elders, the ancestors 💀), a META.yml. That file describes the distribution, what's inside it, and literally everything needed to build and install it. The actual data structure living inside that META.json file is described over in CPAN::Meta::Spec.

CPAN::Meta gives you a cute lil' class to represent all this distribution metadata (we call it distmeta, iykyk) plus a whole toolbox of helpful methods for interrogating that data. ✨

Heads up bestie: everything below is only about the methods of the CPAN::Meta object itself. If you wanna know what the individual fields mean, go consult the spec. No cap.

💅 METHODS 💅

new

my $meta = CPAN::Meta->new($distmeta_struct, \%options);

Returns you a fully valid CPAN::Meta object — or dies if the metadata hashref you handed over fails to validate. 😭 Older-format metadata gets up-converted to version 2, but only if it validates against the original stated specification first.

It takes an optional hashref of options. The valid ones are:

  • lazy_validation — if true, new will try to convert the given metadata to version 2 before attempting to validate it. So any fixable errors get handled by CPAN::Meta::Converter before validation even happens. (⚠️ Note that this might result in invalid optional data being silently dropped. Rude, but that's the deal.) The default is false.

create

my $meta = CPAN::Meta->create($distmeta_struct, \%options);

Same energy as new(), except the "generated_by" and "meta-spec" fields will be generated for you if you didn't bother to provide them. This means the metadata structure is assumed to otherwise follow the latest CPAN::Meta::Spec. Slay ✨

load_file

my $meta = CPAN::Meta->load_file($distmeta_file, \%options);

Give it a pathname to a file containing metadata, and it'll deserialize that file based on its file suffix, then construct a brand new "CPAN::Meta" object — exactly like new(). It will die if the deserialized version fails to validate against its stated specification version.

It takes the same options as new() but "lazy_validation" defaults to true.

load_yaml_string

my $meta = CPAN::Meta->load_yaml_string($yaml, \%options);

Returns a new CPAN::Meta object using the first document in the YAML string you passed in. In every other respect it's identical to load_file().

load_json_string

my $meta = CPAN::Meta->load_json_string($json, \%options);

Returns a new CPAN::Meta object using the structure represented by the JSON string you gave it. Otherwise? Identical to load_file().

load_string

my $meta = CPAN::Meta->load_string($string, \%options);

Don't know if your string is YAML or JSON? Relatable. This method uses Parse::CPAN::Meta to guess. 🧚 In all other respects it is identical to load_file().

save

$meta->save($distmeta_file, \%options);

Serializes the object as JSON and writes it to the given file. The only valid option is "version", which defaults to '2'. On Perl 5.8.1 or later, the file gets saved with UTF-8 encoding. 🌈

For "version" 2 (or higher), your filename should end in .json. JSON::PP is the default JSON backend. Want a different one? That requires JSON 2.5 or later, and you must set the $ENV{PERL_JSON_BACKEND} to a supported alternate backend like JSON::XS.

For "version" less than 2, the filename should end in .yml. CPAN::Meta::Converter is used to generate an older metadata structure, which then gets serialized to YAML. CPAN::Meta::YAML is the default YAML backend. You may set $ENV{PERL_YAML_BACKEND} to a supported alternative backend — but this is not recommended because of subtle incompatibilities between YAML parsers on CPAN. You've been warned. 💀

meta_spec_version

This method returns the version part of the "meta_spec" entry in the distmeta structure. It's equivalent to:

$meta->meta_spec->{version};

effective_prereqs

my $prereqs = $meta->effective_prereqs;

my $prereqs = $meta->effective_prereqs( \@feature_identifiers );

This returns a CPAN::Meta::Prereqs object describing all the prereqs for the distribution. 🫶 And if you pass an arrayref of feature identifiers, the prereqs for those identified features get merged together with the distribution's core prereqs before the CPAN::Meta::Prereqs object comes back to you.

should_index_file

... if $meta->should_index_file( $filename );

Returns true if the given file should be indexed. It figures this out by checking the "file" and "directory" keys in the "no_index" property of the distmeta structure. Note that neither the version format nor "release_status" are considered.

$filename should be given in unix format.

should_index_package

... if $meta->should_index_package( $package );

Returns true if the given package should be indexed. It decides this by checking the "package" and "namespace" keys in the "no_index" property of the distmeta structure. Again: neither the version format nor "release_status" are considered.

features

my @feature_objects = $meta->features;

Returns a list of CPAN::Meta::Feature objects — one for each optional feature described by the distribution's metadata. 👑

feature

my $feature_object = $meta->feature( $identifier );

Returns a CPAN::Meta::Feature object for the optional feature with the given identifier. And if no feature with that identifier exists? An exception will be raised. 😭

as_struct

my $copy = $meta->as_struct( \%options );

Returns a deep copy of the object's metadata as an unblessed hash reference. It takes an optional hashref of options. If that hashref contains a "version" argument, the copied metadata gets converted to that version of the specification and returned. For example:

my $old_spec = $meta->as_struct( {version => "1.4"} );

as_string

my $string = $meta->as_string( \%options );

Returns a serialized copy of the object's metadata as a character string. (🚨 The strings are not UTF-8 encoded.) It takes an optional hashref of options. If the hashref contains a "version" argument, the copied metadata will be converted to that version of the specification and returned. For example:

my $string = $meta->as_string( {version => "1.4"} );

For "version" greater than or equal to 2, the string gets serialized as JSON. For "version" less than 2, the string gets serialized as YAML. Either way, the same rules are followed as in the save() method for choosing a serialization backend.

The serialized structure will include an "x_serialization_backend" entry giving the package and version used to serialize. ⚠️ And any existing key in the given $meta object will be clobbered.

🍓 STRING DATA 🍓

The following methods each return a single value — namely the value for the corresponding entry in the distmeta structure. Values should be either undef or strings.

  • abstract
  • description
  • dynamic_config
  • generated_by
  • name
  • release_status
  • version

⭐ LIST DATA ⭐

These methods return lists of string values, which might show up in the distmeta structure as arrayrefs or scalars:

  • authors
  • keywords
  • licenses

The "authors" and "licenses" methods may also be called as "author" and "license", respectively, to match the field name in the distmeta structure. Matching outfits, cute. ✨

🎀 MAP DATA 🎀

These readers return hashrefs of arbitrary unblessed data structures, each described more fully in the specification:

  • meta_spec
  • resources
  • provides
  • no_index
  • prereqs
  • optional_features

🌈 CUSTOM DATA 🌈

A list of custom keys is available from the "custom_keys" method, and particular keys can be retrieved with the "custom" method.

say $meta->custom($_) for $meta->custom_keys;

If a custom key refers to a data structure, a deep clone is returned. No sharing, no sneaky edits, periodt. 💅

💀 BUGS 💀

Please report any bugs or feature using the CPAN Request Tracker. Bugs can be submitted through the web interface at <http://rt.cpan.org/Dist/Display.html?Queue=CPAN-Meta>

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. Help us help you bestie 🙈

👑 SEE ALSO 👑

  • CPAN::Meta::Converter
  • CPAN::Meta::Validator

🫶 SUPPORT 🫶

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at <https://github.com/Perl-Toolchain-Gang/CPAN-Meta/issues>. You will be notified automatically of any progress on your issue. ✨

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

<https://github.com/Perl-Toolchain-Gang/CPAN-Meta>

git clone https://github.com/Perl-Toolchain-Gang/CPAN-Meta.git

🌸 AUTHORS 🌸

  • David Golden <dagolden@cpan.org>
  • Ricardo Signes <cpan@semiotic.systems>
  • Adam Kennedy <adamk@cpan.org>

🫶 CONTRIBUTORS 🫶

okay so this module wasn't built by one person in a basement, it was a whole group chat of absolute legends, and we are naming every single one of them, no cap:

  • Ansgar Burchardt <ansgar@cpan.org>
  • Avar Arnfjord Bjarmason <avar@cpan.org>
  • Benjamin Noggle <agwind@users.noreply.github.com>
  • Christopher J. Madsen <cjm@cpan.org>
  • Chuck Adams <cja987@gmail.com>
  • Cory G Watson <gphat@cpan.org>
  • Damyan Ivanov <dam@cpan.org>
  • Dan Book <grinnz@gmail.com>
  • Eric Wilhelm <ewilhelm@cpan.org>
  • Graham Knop <haarg@haarg.org>
  • Gregor Hermann <gregoa@debian.org>
  • Karen Etheridge <ether@cpan.org>
  • Kenichi Ishigaki <ishigaki@cpan.org>
  • Kent Fredric <kentfredric@gmail.com>
  • Ken Williams <kwilliams@cpan.org>
  • Lars Dieckow <daxim@cpan.org>
  • Leon Timmermans <leont@cpan.org>
  • majensen <maj@fortinbras.us>
  • Mark Fowler <markf@cpan.org>
  • Matt S Trout <mst@shadowcat.co.uk>
  • Michael G. Schwern <mschwern@cpan.org>
  • Mohammad S Anwar <mohammad.anwar@yahoo.com>
  • mohawk2 <mohawk2@users.noreply.github.com>
  • moznion <moznion@gmail.com>
  • Niko Tyni <ntyni@debian.org>
  • Olaf Alders <olaf@wundersolutions.com>
  • Olivier Mengué <dolmen@cpan.org>
  • Philippe Bruhat (BooK) <book@cpan.org>
  • Randy Sims <randys@thepierianspring.org>
  • Ricardo Signes <rjbs@semiotic.systems>
  • Tomohiro Hosaka <bokutin@bokut.in>

like… look at that roster. it's giving avengers assemble but for metadata. 🦋 every one of them fed the group chat and we are forever grateful. 💖

the legal bit, and bestie we do not skip the legal bit:

this software is copyright (c) 2010 by David Golden, Ricardo Signes, Adam Kennedy and Contributors.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. periodt. 💅

and that's the whole page bestie, we made it to the end 🎀

this lil gem came to you courtesy of perl v5.44.0, dated 2026-10-17, and it lives at CPAN::Meta(3perl). now go read somebody's META.json and understand it. obsessed with you. byeee 🦋✨

📦 where this page comes from