1use 5.006; 2use strict; 3use warnings; 4package CPAN::Meta; 5our $VERSION = '2.140640'; # VERSION 6 7# =head1 SYNOPSIS 8# 9# use v5.10; 10# use strict; 11# use warnings; 12# use CPAN::Meta; 13# use Module::Load; 14# 15# my $meta = CPAN::Meta->load_file('META.json'); 16# 17# printf "testing requirements for %s version %s\n", 18# $meta->name, 19# $meta->version; 20# 21# my $prereqs = $meta->effective_prereqs; 22# 23# for my $phase ( qw/configure runtime build test/ ) { 24# say "Requirements for $phase:"; 25# my $reqs = $prereqs->requirements_for($phase, "requires"); 26# for my $module ( sort $reqs->required_modules ) { 27# my $status; 28# if ( eval { load $module unless $module eq 'perl'; 1 } ) { 29# my $version = $module eq 'perl' ? $] : $module->VERSION; 30# $status = $reqs->accepts_module($module, $version) 31# ? "$version ok" : "$version not ok"; 32# } else { 33# $status = "missing" 34# }; 35# say " $module ($status)"; 36# } 37# } 38# 39# =head1 DESCRIPTION 40# 41# Software distributions released to the CPAN include a F<META.json> or, for 42# older distributions, F<META.yml>, which describes the distribution, its 43# contents, and the requirements for building and installing the distribution. 44# The data structure stored in the F<META.json> file is described in 45# L<CPAN::Meta::Spec>. 46# 47# CPAN::Meta provides a simple class to represent this distribution metadata (or 48# I<distmeta>), along with some helpful methods for interrogating that data. 49# 50# The documentation below is only for the methods of the CPAN::Meta object. For 51# information on the meaning of individual fields, consult the spec. 52# 53# =cut 54 55use Carp qw(carp croak); 56use CPAN::Meta::Feature; 57use CPAN::Meta::Prereqs; 58use CPAN::Meta::Converter; 59use CPAN::Meta::Validator; 60use Parse::CPAN::Meta 1.4414 (); 61 62BEGIN { *_dclone = \&CPAN::Meta::Converter::_dclone } 63 64# =head1 STRING DATA 65# 66# The following methods return a single value, which is the value for the 67# corresponding entry in the distmeta structure. Values should be either undef 68# or strings. 69# 70# =for :list 71# * abstract 72# * description 73# * dynamic_config 74# * generated_by 75# * name 76# * release_status 77# * version 78# 79# =cut 80 81BEGIN { 82 my @STRING_READERS = qw( 83 abstract 84 description 85 dynamic_config 86 generated_by 87 name 88 release_status 89 version 90 ); 91 92 no strict 'refs'; 93 for my $attr (@STRING_READERS) { 94 *$attr = sub { $_[0]{ $attr } }; 95 } 96} 97 98# =head1 LIST DATA 99# 100# These methods return lists of string values, which might be represented in the 101# distmeta structure as arrayrefs or scalars: 102# 103# =for :list 104# * authors 105# * keywords 106# * licenses 107# 108# The C<authors> and C<licenses> methods may also be called as C<author> and 109# C<license>, respectively, to match the field name in the distmeta structure. 110# 111# =cut 112 113BEGIN { 114 my @LIST_READERS = qw( 115 author 116 keywords 117 license 118 ); 119 120 no strict 'refs'; 121 for my $attr (@LIST_READERS) { 122 *$attr = sub { 123 my $value = $_[0]{ $attr }; 124 croak "$attr must be called in list context" 125 unless wantarray; 126 return @{ _dclone($value) } if ref $value; 127 return $value; 128 }; 129 } 130} 131 132sub authors { $_[0]->author } 133sub licenses { $_[0]->license } 134 135# =head1 MAP DATA 136# 137# These readers return hashrefs of arbitrary unblessed data structures, each 138# described more fully in the specification: 139# 140# =for :list 141# * meta_spec 142# * resources 143# * provides 144# * no_index 145# * prereqs 146# * optional_features 147# 148# =cut 149 150BEGIN { 151 my @MAP_READERS = qw( 152 meta-spec 153 resources 154 provides 155 no_index 156 157 prereqs 158 optional_features 159 ); 160 161 no strict 'refs'; 162 for my $attr (@MAP_READERS) { 163 (my $subname = $attr) =~ s/-/_/; 164 *$subname = sub { 165 my $value = $_[0]{ $attr }; 166 return _dclone($value) if $value; 167 return {}; 168 }; 169 } 170} 171 172# =head1 CUSTOM DATA 173# 174# A list of custom keys are available from the C<custom_keys> method and 175# particular keys may be retrieved with the C<custom> method. 176# 177# say $meta->custom($_) for $meta->custom_keys; 178# 179# If a custom key refers to a data structure, a deep clone is returned. 180# 181# =cut 182 183sub custom_keys { 184 return grep { /^x_/i } keys %{$_[0]}; 185} 186 187sub custom { 188 my ($self, $attr) = @_; 189 my $value = $self->{$attr}; 190 return _dclone($value) if ref $value; 191 return $value; 192} 193 194# =method new 195# 196# my $meta = CPAN::Meta->new($distmeta_struct, \%options); 197# 198# Returns a valid CPAN::Meta object or dies if the supplied metadata hash 199# reference fails to validate. Older-format metadata will be up-converted to 200# version 2 if they validate against the original stated specification. 201# 202# It takes an optional hashref of options. Valid options include: 203# 204# =over 205# 206# =item * 207# 208# lazy_validation -- if true, new will attempt to convert the given metadata 209# to version 2 before attempting to validate it. This means than any 210# fixable errors will be handled by CPAN::Meta::Converter before validation. 211# (Note that this might result in invalid optional data being silently 212# dropped.) The default is false. 213# 214# =back 215# 216# =cut 217 218sub _new { 219 my ($class, $struct, $options) = @_; 220 my $self; 221 222 if ( $options->{lazy_validation} ) { 223 # try to convert to a valid structure; if succeeds, then return it 224 my $cmc = CPAN::Meta::Converter->new( $struct ); 225 $self = $cmc->convert( version => 2 ); # valid or dies 226 return bless $self, $class; 227 } 228 else { 229 # validate original struct 230 my $cmv = CPAN::Meta::Validator->new( $struct ); 231 unless ( $cmv->is_valid) { 232 die "Invalid metadata structure. Errors: " 233 . join(", ", $cmv->errors) . "\n"; 234 } 235 } 236 237 # up-convert older spec versions 238 my $version = $struct->{'meta-spec'}{version} || '1.0'; 239 if ( $version == 2 ) { 240 $self = $struct; 241 } 242 else { 243 my $cmc = CPAN::Meta::Converter->new( $struct ); 244 $self = $cmc->convert( version => 2 ); 245 } 246 247 return bless $self, $class; 248} 249 250sub new { 251 my ($class, $struct, $options) = @_; 252 my $self = eval { $class->_new($struct, $options) }; 253 croak($@) if $@; 254 return $self; 255} 256 257# =method create 258# 259# my $meta = CPAN::Meta->create($distmeta_struct, \%options); 260# 261# This is same as C<new()>, except that C<generated_by> and C<meta-spec> fields 262# will be generated if not provided. This means the metadata structure is 263# assumed to otherwise follow the latest L<CPAN::Meta::Spec>. 264# 265# =cut 266 267sub create { 268 my ($class, $struct, $options) = @_; 269 my $version = __PACKAGE__->VERSION || 2; 270 $struct->{generated_by} ||= __PACKAGE__ . " version $version" ; 271 $struct->{'meta-spec'}{version} ||= int($version); 272 my $self = eval { $class->_new($struct, $options) }; 273 croak ($@) if $@; 274 return $self; 275} 276 277# =method load_file 278# 279# my $meta = CPAN::Meta->load_file($distmeta_file, \%options); 280# 281# Given a pathname to a file containing metadata, this deserializes the file 282# according to its file suffix and constructs a new C<CPAN::Meta> object, just 283# like C<new()>. It will die if the deserialized version fails to validate 284# against its stated specification version. 285# 286# It takes the same options as C<new()> but C<lazy_validation> defaults to 287# true. 288# 289# =cut 290 291sub load_file { 292 my ($class, $file, $options) = @_; 293 $options->{lazy_validation} = 1 unless exists $options->{lazy_validation}; 294 295 croak "load_file() requires a valid, readable filename" 296 unless -r $file; 297 298 my $self; 299 eval { 300 my $struct = Parse::CPAN::Meta->load_file( $file ); 301 $self = $class->_new($struct, $options); 302 }; 303 croak($@) if $@; 304 return $self; 305} 306 307# =method load_yaml_string 308# 309# my $meta = CPAN::Meta->load_yaml_string($yaml, \%options); 310# 311# This method returns a new CPAN::Meta object using the first document in the 312# given YAML string. In other respects it is identical to C<load_file()>. 313# 314# =cut 315 316sub load_yaml_string { 317 my ($class, $yaml, $options) = @_; 318 $options->{lazy_validation} = 1 unless exists $options->{lazy_validation}; 319 320 my $self; 321 eval { 322 my ($struct) = Parse::CPAN::Meta->load_yaml_string( $yaml ); 323 $self = $class->_new($struct, $options); 324 }; 325 croak($@) if $@; 326 return $self; 327} 328 329# =method load_json_string 330# 331# my $meta = CPAN::Meta->load_json_string($json, \%options); 332# 333# This method returns a new CPAN::Meta object using the structure represented by 334# the given JSON string. In other respects it is identical to C<load_file()>. 335# 336# =cut 337 338sub load_json_string { 339 my ($class, $json, $options) = @_; 340 $options->{lazy_validation} = 1 unless exists $options->{lazy_validation}; 341 342 my $self; 343 eval { 344 my $struct = Parse::CPAN::Meta->load_json_string( $json ); 345 $self = $class->_new($struct, $options); 346 }; 347 croak($@) if $@; 348 return $self; 349} 350 351# =method load_string 352# 353# my $meta = CPAN::Meta->load_string($string, \%options); 354# 355# If you don't know if a string contains YAML or JSON, this method will use 356# L<Parse::CPAN::Meta> to guess. In other respects it is identical to 357# C<load_file()>. 358# 359# =cut 360 361sub load_string { 362 my ($class, $string, $options) = @_; 363 $options->{lazy_validation} = 1 unless exists $options->{lazy_validation}; 364 365 my $self; 366 eval { 367 my $struct = Parse::CPAN::Meta->load_string( $string ); 368 $self = $class->_new($struct, $options); 369 }; 370 croak($@) if $@; 371 return $self; 372} 373 374# =method save 375# 376# $meta->save($distmeta_file, \%options); 377# 378# Serializes the object as JSON and writes it to the given file. The only valid 379# option is C<version>, which defaults to '2'. On Perl 5.8.1 or later, the file 380# is saved with UTF-8 encoding. 381# 382# For C<version> 2 (or higher), the filename should end in '.json'. L<JSON::PP> 383# is the default JSON backend. Using another JSON backend requires L<JSON> 2.5 or 384# later and you must set the C<$ENV{PERL_JSON_BACKEND}> to a supported alternate 385# backend like L<JSON::XS>. 386# 387# For C<version> less than 2, the filename should end in '.yml'. 388# L<CPAN::Meta::Converter> is used to generate an older metadata structure, which 389# is serialized to YAML. CPAN::Meta::YAML is the default YAML backend. You may 390# set the C<$ENV{PERL_YAML_BACKEND}> to a supported alternative backend, though 391# this is not recommended due to subtle incompatibilities between YAML parsers on 392# CPAN. 393# 394# =cut 395 396sub save { 397 my ($self, $file, $options) = @_; 398 399 my $version = $options->{version} || '2'; 400 my $layer = $] ge '5.008001' ? ':utf8' : ''; 401 402 if ( $version ge '2' ) { 403 carp "'$file' should end in '.json'" 404 unless $file =~ m{\.json$}; 405 } 406 else { 407 carp "'$file' should end in '.yml'" 408 unless $file =~ m{\.yml$}; 409 } 410 411 my $data = $self->as_string( $options ); 412 open my $fh, ">$layer", $file 413 or die "Error opening '$file' for writing: $!\n"; 414 415 print {$fh} $data; 416 close $fh 417 or die "Error closing '$file': $!\n"; 418 419 return 1; 420} 421 422# =method meta_spec_version 423# 424# This method returns the version part of the C<meta_spec> entry in the distmeta 425# structure. It is equivalent to: 426# 427# $meta->meta_spec->{version}; 428# 429# =cut 430 431sub meta_spec_version { 432 my ($self) = @_; 433 return $self->meta_spec->{version}; 434} 435 436# =method effective_prereqs 437# 438# my $prereqs = $meta->effective_prereqs; 439# 440# my $prereqs = $meta->effective_prereqs( \@feature_identifiers ); 441# 442# This method returns a L<CPAN::Meta::Prereqs> object describing all the 443# prereqs for the distribution. If an arrayref of feature identifiers is given, 444# the prereqs for the identified features are merged together with the 445# distribution's core prereqs before the CPAN::Meta::Prereqs object is returned. 446# 447# =cut 448 449sub effective_prereqs { 450 my ($self, $features) = @_; 451 $features ||= []; 452 453 my $prereq = CPAN::Meta::Prereqs->new($self->prereqs); 454 455 return $prereq unless @$features; 456 457 my @other = map {; $self->feature($_)->prereqs } @$features; 458 459 return $prereq->with_merged_prereqs(\@other); 460} 461 462# =method should_index_file 463# 464# ... if $meta->should_index_file( $filename ); 465# 466# This method returns true if the given file should be indexed. It decides this 467# by checking the C<file> and C<directory> keys in the C<no_index> property of 468# the distmeta structure. 469# 470# C<$filename> should be given in unix format. 471# 472# =cut 473 474sub should_index_file { 475 my ($self, $filename) = @_; 476 477 for my $no_index_file (@{ $self->no_index->{file} || [] }) { 478 return if $filename eq $no_index_file; 479 } 480 481 for my $no_index_dir (@{ $self->no_index->{directory} }) { 482 $no_index_dir =~ s{$}{/} unless $no_index_dir =~ m{/\z}; 483 return if index($filename, $no_index_dir) == 0; 484 } 485 486 return 1; 487} 488 489# =method should_index_package 490# 491# ... if $meta->should_index_package( $package ); 492# 493# This method returns true if the given package should be indexed. It decides 494# this by checking the C<package> and C<namespace> keys in the C<no_index> 495# property of the distmeta structure. 496# 497# =cut 498 499sub should_index_package { 500 my ($self, $package) = @_; 501 502 for my $no_index_pkg (@{ $self->no_index->{package} || [] }) { 503 return if $package eq $no_index_pkg; 504 } 505 506 for my $no_index_ns (@{ $self->no_index->{namespace} }) { 507 return if index($package, "${no_index_ns}::") == 0; 508 } 509 510 return 1; 511} 512 513# =method features 514# 515# my @feature_objects = $meta->features; 516# 517# This method returns a list of L<CPAN::Meta::Feature> objects, one for each 518# optional feature described by the distribution's metadata. 519# 520# =cut 521 522sub features { 523 my ($self) = @_; 524 525 my $opt_f = $self->optional_features; 526 my @features = map {; CPAN::Meta::Feature->new($_ => $opt_f->{ $_ }) } 527 keys %$opt_f; 528 529 return @features; 530} 531 532# =method feature 533# 534# my $feature_object = $meta->feature( $identifier ); 535# 536# This method returns a L<CPAN::Meta::Feature> object for the optional feature 537# with the given identifier. If no feature with that identifier exists, an 538# exception will be raised. 539# 540# =cut 541 542sub feature { 543 my ($self, $ident) = @_; 544 545 croak "no feature named $ident" 546 unless my $f = $self->optional_features->{ $ident }; 547 548 return CPAN::Meta::Feature->new($ident, $f); 549} 550 551# =method as_struct 552# 553# my $copy = $meta->as_struct( \%options ); 554# 555# This method returns a deep copy of the object's metadata as an unblessed hash 556# reference. It takes an optional hashref of options. If the hashref contains 557# a C<version> argument, the copied metadata will be converted to the version 558# of the specification and returned. For example: 559# 560# my $old_spec = $meta->as_struct( {version => "1.4"} ); 561# 562# =cut 563 564sub as_struct { 565 my ($self, $options) = @_; 566 my $struct = _dclone($self); 567 if ( $options->{version} ) { 568 my $cmc = CPAN::Meta::Converter->new( $struct ); 569 $struct = $cmc->convert( version => $options->{version} ); 570 } 571 return $struct; 572} 573 574# =method as_string 575# 576# my $string = $meta->as_string( \%options ); 577# 578# This method returns a serialized copy of the object's metadata as a character 579# string. (The strings are B<not> UTF-8 encoded.) It takes an optional hashref 580# of options. If the hashref contains a C<version> argument, the copied metadata 581# will be converted to the version of the specification and returned. For 582# example: 583# 584# my $string = $meta->as_string( {version => "1.4"} ); 585# 586# For C<version> greater than or equal to 2, the string will be serialized as 587# JSON. For C<version> less than 2, the string will be serialized as YAML. In 588# both cases, the same rules are followed as in the C<save()> method for choosing 589# a serialization backend. 590# 591# =cut 592 593sub as_string { 594 my ($self, $options) = @_; 595 596 my $version = $options->{version} || '2'; 597 598 my $struct; 599 if ( $self->meta_spec_version ne $version ) { 600 my $cmc = CPAN::Meta::Converter->new( $self->as_struct ); 601 $struct = $cmc->convert( version => $version ); 602 } 603 else { 604 $struct = $self->as_struct; 605 } 606 607 my ($data, $backend); 608 if ( $version ge '2' ) { 609 $backend = Parse::CPAN::Meta->json_backend(); 610 $data = $backend->new->pretty->canonical->encode($struct); 611 } 612 else { 613 $backend = Parse::CPAN::Meta->yaml_backend(); 614 $data = eval { no strict 'refs'; &{"$backend\::Dump"}($struct) }; 615 if ( $@ ) { 616 croak $backend->can('errstr') ? $backend->errstr : $@ 617 } 618 } 619 620 return $data; 621} 622 623# Used by JSON::PP, etc. for "convert_blessed" 624sub TO_JSON { 625 return { %{ $_[0] } }; 626} 627 6281; 629 630# ABSTRACT: the distribution metadata for a CPAN dist 631 632__END__ 633 634=pod 635 636=encoding UTF-8 637 638=head1 NAME 639 640CPAN::Meta - the distribution metadata for a CPAN dist 641 642=head1 VERSION 643 644version 2.140640 645 646=head1 SYNOPSIS 647 648 use v5.10; 649 use strict; 650 use warnings; 651 use CPAN::Meta; 652 use Module::Load; 653 654 my $meta = CPAN::Meta->load_file('META.json'); 655 656 printf "testing requirements for %s version %s\n", 657 $meta->name, 658 $meta->version; 659 660 my $prereqs = $meta->effective_prereqs; 661 662 for my $phase ( qw/configure runtime build test/ ) { 663 say "Requirements for $phase:"; 664 my $reqs = $prereqs->requirements_for($phase, "requires"); 665 for my $module ( sort $reqs->required_modules ) { 666 my $status; 667 if ( eval { load $module unless $module eq 'perl'; 1 } ) { 668 my $version = $module eq 'perl' ? $] : $module->VERSION; 669 $status = $reqs->accepts_module($module, $version) 670 ? "$version ok" : "$version not ok"; 671 } else { 672 $status = "missing" 673 }; 674 say " $module ($status)"; 675 } 676 } 677 678=head1 DESCRIPTION 679 680Software distributions released to the CPAN include a F<META.json> or, for 681older distributions, F<META.yml>, which describes the distribution, its 682contents, and the requirements for building and installing the distribution. 683The data structure stored in the F<META.json> file is described in 684L<CPAN::Meta::Spec>. 685 686CPAN::Meta provides a simple class to represent this distribution metadata (or 687I<distmeta>), along with some helpful methods for interrogating that data. 688 689The documentation below is only for the methods of the CPAN::Meta object. For 690information on the meaning of individual fields, consult the spec. 691 692=head1 METHODS 693 694=head2 new 695 696 my $meta = CPAN::Meta->new($distmeta_struct, \%options); 697 698Returns a valid CPAN::Meta object or dies if the supplied metadata hash 699reference fails to validate. Older-format metadata will be up-converted to 700version 2 if they validate against the original stated specification. 701 702It takes an optional hashref of options. Valid options include: 703 704=over 705 706=item * 707 708lazy_validation -- if true, new will attempt to convert the given metadata 709to version 2 before attempting to validate it. This means than any 710fixable errors will be handled by CPAN::Meta::Converter before validation. 711(Note that this might result in invalid optional data being silently 712dropped.) The default is false. 713 714=back 715 716=head2 create 717 718 my $meta = CPAN::Meta->create($distmeta_struct, \%options); 719 720This is same as C<new()>, except that C<generated_by> and C<meta-spec> fields 721will be generated if not provided. This means the metadata structure is 722assumed to otherwise follow the latest L<CPAN::Meta::Spec>. 723 724=head2 load_file 725 726 my $meta = CPAN::Meta->load_file($distmeta_file, \%options); 727 728Given a pathname to a file containing metadata, this deserializes the file 729according to its file suffix and constructs a new C<CPAN::Meta> object, just 730like C<new()>. It will die if the deserialized version fails to validate 731against its stated specification version. 732 733It takes the same options as C<new()> but C<lazy_validation> defaults to 734true. 735 736=head2 load_yaml_string 737 738 my $meta = CPAN::Meta->load_yaml_string($yaml, \%options); 739 740This method returns a new CPAN::Meta object using the first document in the 741given YAML string. In other respects it is identical to C<load_file()>. 742 743=head2 load_json_string 744 745 my $meta = CPAN::Meta->load_json_string($json, \%options); 746 747This method returns a new CPAN::Meta object using the structure represented by 748the given JSON string. In other respects it is identical to C<load_file()>. 749 750=head2 load_string 751 752 my $meta = CPAN::Meta->load_string($string, \%options); 753 754If you don't know if a string contains YAML or JSON, this method will use 755L<Parse::CPAN::Meta> to guess. In other respects it is identical to 756C<load_file()>. 757 758=head2 save 759 760 $meta->save($distmeta_file, \%options); 761 762Serializes the object as JSON and writes it to the given file. The only valid 763option is C<version>, which defaults to '2'. On Perl 5.8.1 or later, the file 764is saved with UTF-8 encoding. 765 766For C<version> 2 (or higher), the filename should end in '.json'. L<JSON::PP> 767is the default JSON backend. Using another JSON backend requires L<JSON> 2.5 or 768later and you must set the C<$ENV{PERL_JSON_BACKEND}> to a supported alternate 769backend like L<JSON::XS>. 770 771For C<version> less than 2, the filename should end in '.yml'. 772L<CPAN::Meta::Converter> is used to generate an older metadata structure, which 773is serialized to YAML. CPAN::Meta::YAML is the default YAML backend. You may 774set the C<$ENV{PERL_YAML_BACKEND}> to a supported alternative backend, though 775this is not recommended due to subtle incompatibilities between YAML parsers on 776CPAN. 777 778=head2 meta_spec_version 779 780This method returns the version part of the C<meta_spec> entry in the distmeta 781structure. It is equivalent to: 782 783 $meta->meta_spec->{version}; 784 785=head2 effective_prereqs 786 787 my $prereqs = $meta->effective_prereqs; 788 789 my $prereqs = $meta->effective_prereqs( \@feature_identifiers ); 790 791This method returns a L<CPAN::Meta::Prereqs> object describing all the 792prereqs for the distribution. If an arrayref of feature identifiers is given, 793the prereqs for the identified features are merged together with the 794distribution's core prereqs before the CPAN::Meta::Prereqs object is returned. 795 796=head2 should_index_file 797 798 ... if $meta->should_index_file( $filename ); 799 800This method returns true if the given file should be indexed. It decides this 801by checking the C<file> and C<directory> keys in the C<no_index> property of 802the distmeta structure. 803 804C<$filename> should be given in unix format. 805 806=head2 should_index_package 807 808 ... if $meta->should_index_package( $package ); 809 810This method returns true if the given package should be indexed. It decides 811this by checking the C<package> and C<namespace> keys in the C<no_index> 812property of the distmeta structure. 813 814=head2 features 815 816 my @feature_objects = $meta->features; 817 818This method returns a list of L<CPAN::Meta::Feature> objects, one for each 819optional feature described by the distribution's metadata. 820 821=head2 feature 822 823 my $feature_object = $meta->feature( $identifier ); 824 825This method returns a L<CPAN::Meta::Feature> object for the optional feature 826with the given identifier. If no feature with that identifier exists, an 827exception will be raised. 828 829=head2 as_struct 830 831 my $copy = $meta->as_struct( \%options ); 832 833This method returns a deep copy of the object's metadata as an unblessed hash 834reference. It takes an optional hashref of options. If the hashref contains 835a C<version> argument, the copied metadata will be converted to the version 836of the specification and returned. For example: 837 838 my $old_spec = $meta->as_struct( {version => "1.4"} ); 839 840=head2 as_string 841 842 my $string = $meta->as_string( \%options ); 843 844This method returns a serialized copy of the object's metadata as a character 845string. (The strings are B<not> UTF-8 encoded.) It takes an optional hashref 846of options. If the hashref contains a C<version> argument, the copied metadata 847will be converted to the version of the specification and returned. For 848example: 849 850 my $string = $meta->as_string( {version => "1.4"} ); 851 852For C<version> greater than or equal to 2, the string will be serialized as 853JSON. For C<version> less than 2, the string will be serialized as YAML. In 854both cases, the same rules are followed as in the C<save()> method for choosing 855a serialization backend. 856 857=head1 STRING DATA 858 859The following methods return a single value, which is the value for the 860corresponding entry in the distmeta structure. Values should be either undef 861or strings. 862 863=over 4 864 865=item * 866 867abstract 868 869=item * 870 871description 872 873=item * 874 875dynamic_config 876 877=item * 878 879generated_by 880 881=item * 882 883name 884 885=item * 886 887release_status 888 889=item * 890 891version 892 893=back 894 895=head1 LIST DATA 896 897These methods return lists of string values, which might be represented in the 898distmeta structure as arrayrefs or scalars: 899 900=over 4 901 902=item * 903 904authors 905 906=item * 907 908keywords 909 910=item * 911 912licenses 913 914=back 915 916The C<authors> and C<licenses> methods may also be called as C<author> and 917C<license>, respectively, to match the field name in the distmeta structure. 918 919=head1 MAP DATA 920 921These readers return hashrefs of arbitrary unblessed data structures, each 922described more fully in the specification: 923 924=over 4 925 926=item * 927 928meta_spec 929 930=item * 931 932resources 933 934=item * 935 936provides 937 938=item * 939 940no_index 941 942=item * 943 944prereqs 945 946=item * 947 948optional_features 949 950=back 951 952=head1 CUSTOM DATA 953 954A list of custom keys are available from the C<custom_keys> method and 955particular keys may be retrieved with the C<custom> method. 956 957 say $meta->custom($_) for $meta->custom_keys; 958 959If a custom key refers to a data structure, a deep clone is returned. 960 961=for Pod::Coverage TO_JSON abstract author authors custom custom_keys description dynamic_config 962generated_by keywords license licenses meta_spec name no_index 963optional_features prereqs provides release_status resources version 964 965=head1 BUGS 966 967Please report any bugs or feature using the CPAN Request Tracker. 968Bugs can be submitted through the web interface at 969L<http://rt.cpan.org/Dist/Display.html?Queue=CPAN-Meta> 970 971When submitting a bug or request, please include a test-file or a patch to an 972existing test-file that illustrates the bug or desired feature. 973 974=head1 SEE ALSO 975 976=over 4 977 978=item * 979 980L<CPAN::Meta::Converter> 981 982=item * 983 984L<CPAN::Meta::Validator> 985 986=back 987 988=for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan 989 990=head1 SUPPORT 991 992=head2 Bugs / Feature Requests 993 994Please report any bugs or feature requests through the issue tracker 995at L<https://github.com/Perl-Toolchain-Gang/CPAN-Meta/issues>. 996You will be notified automatically of any progress on your issue. 997 998=head2 Source Code 999 1000This is open source software. The code repository is available for 1001public review and contribution under the terms of the license. 1002 1003L<https://github.com/Perl-Toolchain-Gang/CPAN-Meta> 1004 1005 git clone https://github.com/Perl-Toolchain-Gang/CPAN-Meta.git 1006 1007=head1 AUTHORS 1008 1009=over 4 1010 1011=item * 1012 1013David Golden <dagolden@cpan.org> 1014 1015=item * 1016 1017Ricardo Signes <rjbs@cpan.org> 1018 1019=back 1020 1021=head1 CONTRIBUTORS 1022 1023=over 4 1024 1025=item * 1026 1027Ansgar Burchardt <ansgar@cpan.org> 1028 1029=item * 1030 1031Avar Arnfjord Bjarmason <avar@cpan.org> 1032 1033=item * 1034 1035Christopher J. Madsen <cjm@cpan.org> 1036 1037=item * 1038 1039Chuck Adams <cja987@gmail.com> 1040 1041=item * 1042 1043Cory G Watson <gphat@cpan.org> 1044 1045=item * 1046 1047Damyan Ivanov <dam@cpan.org> 1048 1049=item * 1050 1051Eric Wilhelm <ewilhelm@cpan.org> 1052 1053=item * 1054 1055Gregor Hermann <gregoa@debian.org> 1056 1057=item * 1058 1059Karen Etheridge <ether@cpan.org> 1060 1061=item * 1062 1063Ken Williams <kwilliams@cpan.org> 1064 1065=item * 1066 1067Kenichi Ishigaki <ishigaki@cpan.org> 1068 1069=item * 1070 1071Lars Dieckow <daxim@cpan.org> 1072 1073=item * 1074 1075Leon Timmermans <leont@cpan.org> 1076 1077=item * 1078 1079Mark Fowler <markf@cpan.org> 1080 1081=item * 1082 1083Michael G. Schwern <mschwern@cpan.org> 1084 1085=item * 1086 1087Olaf Alders <olaf@wundersolutions.com> 1088 1089=item * 1090 1091Olivier Mengue <dolmen@cpan.org> 1092 1093=item * 1094 1095Randy Sims <randys@thepierianspring.org> 1096 1097=back 1098 1099=head1 COPYRIGHT AND LICENSE 1100 1101This software is copyright (c) 2010 by David Golden and Ricardo Signes. 1102 1103This is free software; you can redistribute it and/or modify it under 1104the same terms as the Perl 5 programming language system itself. 1105 1106=cut 1107