NAME

       Module::CPANfile - Parse cpanfile

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 cpanfile format to load application specific dependencies, not just
       for CPAN distributions.

METHODS

       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 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 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   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  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

SEE ALSO

       cpanfile, CPAN::Meta, CPAN::Meta::Spec

perl v5.36.0                                       2022-11-19                              Module::CPANfile(3pm)