CPAN::Meta::Converter: SYNOPSIS displays non-existent functions

[jkeenan]

The documentation for CPAN::Meta::Converter starts as follows:

NAME
    CPAN::Meta::Converter - Convert CPAN distribution metadata structures

VERSION
    version 2.150010

SYNOPSIS
      my $struct = decode_json_file('META.json');

      my $cmc = CPAN::Meta::Converter->new( $struct );

      my $new_struct = $cmc->convert( version => "2" );

Note that the SYNOPSIS instructs one to use a function called decode_json_file. I tried this in the following:

$ cat META.json 
{
   "abstract" : "Compare elements of two or more lists",
   "author" : [
      "James E Keenan ([email protected])"
   ],
   "dynamic_config" : 1,
   "generated_by" : "ExtUtils::MakeMaker version 7.70, CPAN::Meta::Converter version 2.150010",
   "license" : [
      "perl_5"
   ],
   "meta-spec" : {
      "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",
      "version" : 2
   },
   "name" : "List-Compare",
   "no_index" : {
      "directory" : [
         "t",
         "inc"
      ]
   },
   "prereqs" : {
      "build" : {
         "requires" : {
            "ExtUtils::MakeMaker" : "0"
         }
      },
      "configure" : {
         "requires" : {
            "ExtUtils::MakeMaker" : "0"
         }
      },
      "test" : {
         "requires" : {
            "Capture::Tiny" : "0",
            "Test::Simple" : "0.1"
         }
      }
   },
   "release_status" : "stable",
   "resources" : {
      "bugtracker" : {
         "mailto" : "[email protected]",
         "web" : "https://rt.cpan.org/Public/Dist/Display.html?Name=List-Compare"
      },
      "homepage" : "http://thenceforward.net/perl/modules/List-Compare/",
      "repository" : {
         "type" : "git",
         "url" : "https://github.com/jkeenan/list-compare.git",
         "web" : "https://github.com/jkeenan/list-compare"
      }
   },
   "version" : "0.55",
   "x_serialization_backend" : "JSON::PP version 4.16"
}

$ cat convert-metadata.pl 
#!/usr/bin/env perl
use 5.14.0;
use warnings;
use Carp;
use CPAN::Meta::Converter;

my $jsonfile = './META.json';
croak "Unable to locate $jsonfile" unless -f $jsonfile;

my $struct = decode_json_file($jsonfile);
my $cmc = CPAN::Meta::Converter->new($struct);
my $new_struct = $cmc->convert( version => "2" );

$ perl convert-metadata.pl 
Undefined subroutine &main::decode_json_file called at convert-metadata.pl line 10.

The program fails because there is no such function as decode_json_file. If I add use JSON::PP;, I can use the decode_json() function -- but that is documented as taking a string which is UTF-8 encoded JSON text -- not a .json file.

The non-existent decode_json_file() function is also found in the SYNOPSIS for CPAN::Meta::Validator.

Please revise.

Thank you very much.
Jim Keenan