PARSE::CPAN::META(3perl)

💖 NAME 💖

Parse::CPAN::Meta — ok bestie, this one parses META.yml and META.json CPAN metadata files ✨

---

🎀 VERSION 🎀

version 2.150013 — yes that's the whole number, slay 💅

---

🦋 SYNOPSIS 🦋

Like, imagine you have a file, right? It looks like this:

#############################################
# In your file

---
name: My-Distribution
version: 1.23
resources:
  homepage: "http://example.com/dist/My-Distribution"

And then in your program you're like:

#############################################
# In your program

use Parse::CPAN::Meta;

my $distmeta = Parse::CPAN::Meta->load_file('META.yml');

# Reading properties
my $name     = $distmeta->{name};
my $version  = $distmeta->{version};
my $homepage = $distmeta->{resources}{homepage};

and boom, you got your metadata. main character energy fr fr 👑

---

🌸 DESCRIPTION 🌸

So, Parse::CPAN::Meta is a parser for META.json and META.yml files, and it does that using JSON::PP and/or CPAN::Meta::YAML. iconic collaboration honestly 🫶

It gives you three methods: load_file, load_json_string, and load_yaml_string. These will read and deserialize CPAN metafiles — more on each of them below, in detail, no skipping 💖

It also provides a legacy API of only two functions, based on the YAML functions of the same name. Wherever possible, identical calling semantics are used. You can only use these ones with YAML sources though, just so you know.

All error reporting is done with exceptions (die'ing). so like, brace yourself 😭

⚠️ Also! META files are expected to be in UTF-8 encoding, only. When you convert string data, you have to decode it from UTF-8 first. no negotiation on this one bestie

---

✨ METHODS ✨

💜 load_file

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

my $metadata_structure = Parse::CPAN::Meta->load_file('META.yml');

This reads the file you named and deserializes it into a data structure, and it figures out whether it's JSON or YAML based on the filename. The file gets read using the :utf8 IO layer. cute and efficient 💅

💜 load_yaml_string

my $metadata_structure = Parse::CPAN::Meta->load_yaml_string($yaml_string);

This one deserializes the given string of YAML and returns the first document in it. (CPAN metadata files should always have only one document, btw.) If the source was UTF-8 encoded, the string must be decoded before you call load_yaml_string. yes this matters, i don't make the rules 🙈

💜 load_json_string

my $metadata_structure = Parse::CPAN::Meta->load_json_string($json_string);

Deserializes the given string of JSON and the result. If the source was UTF-8 encoded, the string must be decoded before calling load_json_string. same deal as above bestie 🍓

💜 load_string

my $metadata_structure = Parse::CPAN::Meta->load_string($some_string);

Ok so if you genuinely don't know whether your string is YAML or JSON, this method will use some heuristics and guess. And if it still can't tell? It just assumes YAML. lowkey a vibe ✨

💜 yaml_backend

my $backend = Parse::CPAN::Meta->yaml_backend;

Returns the module name of the YAML serializer. Head to ENVIRONMENT for the details 💖

💜 json_backend

my $backend = Parse::CPAN::Meta->json_backend;

Returns the module name of the JSON serializer. If CPAN_META_JSON_BACKEND is set, this will be whatever that's set to. If it's not set, this will either be JSON::PP or JSON. And if PERL_JSON_BACKEND is set, this will return JSON, because further delegation is handled by the JSON module. See ENVIRONMENT for details 🫶

💜 json_decoder

my $decoder = Parse::CPAN::Meta->json_decoder;

Returns the module name of the JSON decoder. Unlike json_backend, this isn't necessarily a full JSON-style module — it's only something that will provide a decode_json subroutine. If CPAN_META_JSON_DECODER is set, this will be whatever that's set to. If not, this will be whatever has been selected as json_backend. See ENVIRONMENT for more notes 💜

---

🌈 FUNCTIONS 🌈

For maintenance clarity, no functions are exported by default. These functions are available for backwards compatibility only and are best avoided in favor of load_file. like, they're giving nostalgia, not utility 🥲

🌟 Load

my @yaml = Parse::CPAN::Meta::Load( $string );

Parses a string containing a valid YAML stream into a list of Perl data structures.

🌟 LoadFile

my @yaml = Parse::CPAN::Meta::LoadFile( 'META.yml' );

Reads the YAML stream from a file instead of a string. same energy, different source 🎀

---

🧚 ENVIRONMENT 🧚

💖 CPAN_META_JSON_DECODER

By default, JSON::PP will be used for deserializing JSON data. If the CPAN_META_JSON_DECODER environment variable exists, it's expected to be the name of a loadable module that provides a decode_json subroutine, and that's what will then be used for deserialization. Relying only on the existence of said subroutine allows for maximum compatibility, since this API is provided by all of JSON::PP, JSON::XS, Cpanel::JSON::XS, JSON::MaybeXS, JSON::Tiny, and Mojo::JSON. the whole friend group showed up 🫶

💖 CPAN_META_JSON_BACKEND

By default, JSON::PP will be used for deserializing JSON data. If the CPAN_META_JSON_BACKEND environment variable exists, it's expected to be the name of a loadable module that provides the JSON API, since downstream code expects to be able to call new on this class. So while JSON::PP, JSON::XS, Cpanel::JSON::XS and JSON::MaybeXS will work for this, to use Mojo::JSON or JSON::Tiny for decoding you need to set CPAN_META_JSON_DECODER instead. yes it's a whole thing 😭

💖 PERL_JSON_BACKEND

If the CPAN_META_JSON_BACKEND environment variable does not exist, and the PERL_JSON_BACKEND environment variable exists, is true and is not JSON::PP, then the JSON module (version 2.5 or greater) will be loaded and used to interpret PERL_JSON_BACKEND. If JSON is not installed or is too old, an exception will be thrown. And note that at the time of writing, the only useful values are 1, which tells JSON to guess, or JSON::XS — if you want to use a newer JSON module, see CPAN_META_JSON_BACKEND. ok periodt 💅

💖 PERL_YAML_BACKEND

By default, CPAN::Meta::YAML will be used for deserializing YAML data. If the PERL_YAML_BACKEND environment variable is defined, then it's interpreted as a module to use for deserialization. The given module must be installed, must load correctly, and must implement the Load() function — otherwise an exception will be thrown. no half measures 🌸

---

👑 AUTHORS 👑

The legends behind this:

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

the trio we didn't deserve but absolutely needed 💜✨

---

📜 COPYRIGHT AND LICENSE 📜

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. free as in freedom bestie, use it, remix it, ship it 🎀

---

ok that's the whole page, you're officially a Parse::CPAN::Meta girlie now 💅

this was brought to you by perl v5.44.0, dated 2026-10-17, from the Parse::CPAN::Meta(3perl) era — mwah, take care of her 💖✨