Module::CPANfile(3)

🌈 Module::CPANfile(3) — Parse cpanfile 🌈

okay bestie, welcome to the Module::CPANfile(3) page from the User Contributed Perl Documentation — it's all about the module that parses a cpanfile, and it's lowkey iconic. 💅✨

💖 NAME 💖

Module::CPANfile — Parse cpanfile. periodt. 🌸

🦋 SYNOPSIS 🦋

use Module::CPANfile;

my $file = Module::CPANfile->load("cpanfile");
my $prereqs = $file->prereqs; # CPAN::Meta::Prereqs object

my @features = $file->features; # CPAN::Meta::Feature objects
my $merged_prereqs = $file->prereqs_with(@identifiers); # CPAN::Meta::Prereqs

$file->merge_meta('MYMETA.json');

💫 DESCRIPTION 💫

Module::CPANfile is a tool to handle the cpanfile format to load application specific dependencies — not just for CPAN distributions, fr fr. 🫶

🧚 METHODS 🧚

okay so here are the methods, bestie — every single one, no skips. 👑

🌟 load

$file = Module::CPANfile->load;
$file = Module::CPANfile->load('cpanfile');

Load and parse a cpanfile. By default it tries to load "cpanfile" in the current directory, unless you pass the path to its argument. 💖

🌟 from_prereqs

$file = Module::CPANfile->from_prereqs({
  runtime => { requires => { DBI => '1.000' } },
});

Creates a new Module::CPANfile object from the prereqs hash you can get via CPAN::Meta's "prereqs", or CPAN::Meta::Prereqs' "as_string_hash". 🎀

# read MYMETA, then feed the prereqs to create Module::CPANfile
my $meta = CPAN::Meta->load_file('MYMETA.json');
my $file = Module::CPANfile->from_prereqs($meta->prereqs);

# load cpanfile, then recreate it with round-trip
my $file = Module::CPANfile->load('cpanfile');
$file = Module::CPANfile->from_prereqs($file->prereq_specs);
                                  # or $file->prereqs->as_string_hash

🌟 prereqs

Returns the CPAN::Meta::Prereqs object out of the parsed cpanfile. 💜

🌟 prereq_specs

Returns a hash reference that should be passed to "CPAN::Meta::Prereqs->new". 🍓

🌟 features

Returns a list of features available in the cpanfile as CPAN::Meta::Feature. 🧚

🌟 prereqs_with(@identifiers), effective_prereqs(\@identifiers)

Returns a CPAN::Meta::Prereqs object, with merged prereqs for features identified with the @identifiers. ✨

🌟 to_string($include_empty)

$file->to_string;
$file->to_string(1);

Returns a canonical string (code) representation for cpanfile. Useful if you want to convert CPAN::Meta::Prereqs to a new cpanfile. 💅

# read MYMETA's prereqs and print cpanfile representation of it
my $meta = CPAN::Meta->load_file('MYMETA.json');
my $file = Module::CPANfile->from_prereqs($meta->prereqs);
print $file->to_string;

By default, it omits the phase where there're no modules registered. If you pass the argument of a true value, it will print them as well. 👀

🌟 save

$file->save('cpanfile');

Saves the currently loaded prereqs as a new "cpanfile" by calling "to_string". 🎀

⚠️ Beware: this method will overwrite the existing cpanfile without any warning or backup. Taking a backup or giving warnings to users is a caller's responsibility. 😭

# Read MYMETA.json and creates a new cpanfile
my $meta = CPAN::Meta->load_file('MYMETA.json');
my $file = Module::CPANfile->from_prereqs($meta->prereqs);
$file->save('cpanfile');

🌟 merge_meta

$file->merge_meta('META.yml');
$file->merge_meta('MYMETA.json', '2.0');

Merge the effective prereqs with the Meta specification loaded from the given META file, using CPAN::Meta. You can specify the META spec version in the second argument, which defaults to 1.4 in case the given file is YAML, and 2 if it is JSON. 🔥

🌟 options_for_module

my $options = $file->options_for_module($module);

Returns the extra options specified for a given module as a hash reference. Returns "undef" when the given module is not specified in the "cpanfile". 🙈

For example,

# cpanfile
requires 'Plack', '1.000',
  dist => "MIYAGAWA/Plack-1.000.tar.gz";

# ...
my $file = Module::CPANfile->load;
my $options = $file->options_for_module('Plack');
# => { dist => "MIYAGAWA/Plack-1.000.tar.gz" }

👑 AUTHOR 👑

Tatsuhiko Miyagawa — the author, and honestly? iconic. 👑

🦋 SEE ALSO 🦋

Go look at these too, bestie:

• cpanfile
• CPAN::Meta
• CPAN::Meta::Spec

🫶 That's the whole page, bestie — perl v5.42.0, dated 2018-04-27, from the Module::CPANfile(3) manual. Bye ily! 💖