restore old prepare_metadata() API and add get_metadata wrapper

git-svn-id: http://svn.perl.org/modules/Module-Build/trunk@13626 50811bd7-b8ce-0310-adc1-d9db26280581

Changes

@@ -1,6 +1,16 @@
 Revision history for Perl extension Module::Build.
 
-0.35_11 - 
+0.35_11 -
+
+ *** API CHANGE ***
+
+ - The old API for prepare_metadata() has been restored to avoid breaking
+   distributions that were overriding it (e.g. BioPerl), but the method
+   has been marked deprecated and may be made private or may disappear in
+   some future version of Module::Build. [David Golden]
+
+ - A new get_metadata() method has been added as a simpler wrapper around
+   the old, kludgy prepare_metadata() API. [David Golden]
 
 0.35_10 - Tue Nov 24 22:49:19 EST 2009
 

lib/Module/Build/API.pod

@@ -769,7 +769,7 @@ distribution-level share directory.  Alternatively, C<share_dir> can be set to
 a directory name or an arrayref of directory names containing files to be
 installed in the distribution-level share directory.
 
-If C<share_dir> is a hashref, it may have C<dist> or C<module> keys 
+If C<share_dir> is a hashref, it may have C<dist> or C<module> keys
 providing full flexibility in defining share directories to install.
 
   share_dir => {
@@ -1182,7 +1182,7 @@ See also L<Module::Build::Authoring/"SAVING CONFIGURATION INFORMATION">.
 Returns a hash reference indicating the C<conflicts> prerequisites
 that were passed to the C<new()> method.
 
-=item contains_pod($file)
+=item contains_pod($file) [deprecated]
 
 [version 0.20]
 
@@ -1569,7 +1569,7 @@ localized path based on C<$value>.
 
 Assigning the value C<undef> to an element causes it to be removed.
 
-=item prepare_metadata()
+=item get_metadata()
 
 [version 0.36]
 
@@ -1580,13 +1580,34 @@ of F<META.yml>.   E.g.
   package My::Builder;
   use base 'Module::Build';
 
-  sub prepare_metadata {
-    my $self = shift;
-    my $data = $self->SUPER::prepare_metadata();
+  sub get_metadata {
+    my $self, @args = @_;
+    my $data = $self->SUPER::get_metadata(@args);
     $data->{custom_field} = 'foo';
     return $data;
   }
 
+The only valid argument is C<fatal>, which indicates whether missing required
+metadata fields should be a fatal error or not.  For META creation, it
+generally should, but for MYMETA creation for end-users, it should not be
+fatal.
+
+This method is a wrapper around the old prepare_metadata API now that we
+no longer use YAML::Node to hold metadata.
+
+=item prepare_metadata() [deprecated]
+
+[version 0.36]
+
+[Deprecated] As of 0.36, authors should use C<get_metadata> instead.  This
+method is preserved for backwards compatibility only.
+
+It takes three positional arguments: a hashref (to which metadata will be
+added), an optional arrayref (to which metadata keys will be added in order if
+the arrayref exists), and a hashref of arguments (as provided to get_metadata).
+The latter argument is new as of 0.36.  Earlier versions are always fatal on
+errors.
+
 Prior to version 0.36, this method took a YAML::Node as an argument to hold
 assembled metadata.
 

lib/Module/Build/Base.pm

@@ -1778,7 +1778,7 @@ sub create_mymeta {
   }
   # but generate from scratch, ignoring errors if META doesn't exist
   else {
-    $mymeta = $self->prepare_metadata( fatal => 0 );
+    $mymeta = $self->get_metadata( fatal => 0 );
   }
 
   # MYMETA is always static
@@ -4161,7 +4161,7 @@ sub do_create_metafile {
     push @INC, File::Spec->catdir($self->blib, 'lib');
   }
 
-  if ( $self->write_metafile( $self->metafile, $self->prepare_metadata( fatal => 1 ) ) ) {
+  if ($self->write_metafile($self->metafile,$self->get_metadata(fatal=>1))){
     $self->{wrote_metadata} = 1;
     $self->_add_to_manifest('MANIFEST', $metafile);
   }
@@ -4238,16 +4238,34 @@ sub _normalize_prereqs {
   return \%prereq_types;
 }
 
-sub prepare_metadata {
+
+# wrapper around old prepare_metadata API;
+sub get_metadata {
   my ($self, %args) = @_;
-  my $fatal = $args{fatal} || 0;
+  my $metadata = {};
+  $self->prepare_metadata( $metadata, undef, \%args );
+  return $metadata;
+}
+
+# To preserve compatibility with old API, $node *must* be a hashref
+# passed in to prepare_metadata.  $keys is an arrayref holding a
+# list of keys -- it's use is optional and generally no longer needed
+# but kept for back compatibility.  $args is an optional parameter to
+# support the new 'fatal' toggle
+
+sub prepare_metadata {
+  my ($self, $node, $keys, $args) = @_;
+  unless ( ref $node eq 'HASH' ) {
+    croak "prepare_metadata() requires a hashref argument to hold output\n";
+  }
+  my $fatal = $args->{fatal} || 0;
   my $p = $self->{properties};
-  my $node = {};
 
   # A little helper sub
   my $add_node = sub {
     my ($name, $val) = @_;
     $node->{$name} = $val;
+    push @$keys, $name if $keys;
   };
 
   foreach (qw(dist_name dist_version dist_author dist_abstract license)) {

t/extend.t

@@ -186,19 +186,19 @@ print "Hello, World!\n";
 				  meta_add => {foo => 'bar'},
 				  conflicts => {'Foo::Barxx' => 0},
 			        );
-  my $data = $mb->prepare_metadata;
+  my $data = $mb->get_metadata;
   is $data->{foo}, 'bar';
 
   $mb->meta_merge(foo => 'baz');
-  $data = $mb->prepare_metadata;
+  $data = $mb->get_metadata;
   is $data->{foo}, 'baz';
 
   $mb->meta_merge(conflicts => {'Foo::Fooxx' => 0});
-  $data = $mb->prepare_metadata;
+  $data = $mb->get_metadata;
   is_deeply $data->{conflicts}, {'Foo::Barxx' => 0, 'Foo::Fooxx' => 0};
 
   $mb->meta_add(conflicts => {'Foo::Bazxx' => 0});
-  $data = $mb->prepare_metadata;
+  $data = $mb->get_metadata;
   is_deeply $data->{conflicts}, {'Foo::Bazxx' => 0, 'Foo::Fooxx' => 0};
 }
 

t/metadata.t

@@ -65,7 +65,7 @@ my $mb = Module::Build->new_from_context;
   my $mb_config_req = {
     'Module::Build' => int($Module::Build::VERSION * 100)/100
   };
-  my $node = $mb->prepare_metadata( );
+  my $node = $mb->get_metadata( );
 
   # exists() doesn't seem to work here
   is $node->{name}, $metadata{module_name};
@@ -86,7 +86,7 @@ my $mb = Module::Build->new_from_context;
 {
   my $mb_prereq = { 'Module::Build' => 0 };
   $mb->configure_requires( $mb_prereq );
-  my $node = $mb->prepare_metadata( );
+  my $node = $mb->get_metadata( );
 
 
   # exists() doesn't seem to work here
@@ -176,11 +176,11 @@ package Simple::Simon;
 $VERSION = version->new('0.61.' . (qw$Revision: 129 $)[1]);
 ---
   $dist->regen;
-  my $provides = new_build()->prepare_metadata()->{provides};
+  my $provides = new_build()->get_metadata()->{provides};
   is $provides->{'Simple'}{version}, 'v0.60.128', "Check version";
   is $provides->{'Simple::Simon'}{version}, 'v0.61.129', "Check version";
-  is ref($provides->{'Simple'}{version}), '', "Versions from prepare_metadata() aren't refs";
-  is ref($provides->{'Simple::Simon'}{version}), '', "Versions from prepare_metadata() aren't refs";
+  is ref($provides->{'Simple'}{version}), '', "Versions from get_metadata() aren't refs";
+  is ref($provides->{'Simple::Simon'}{version}), '', "Versions from get_metadata() aren't refs";
 }