Initial Commit

database/perl/lib/CPAN/Meta/Check.pm

@@ -0,0 +1,132 @@
+package CPAN::Meta::Check;
+$CPAN::Meta::Check::VERSION = '0.014';
+use strict;
+use warnings;
+
+use base 'Exporter';
+our @EXPORT = qw//;
+our @EXPORT_OK = qw/check_requirements requirements_for verify_dependencies/;
+our %EXPORT_TAGS = (all => [ @EXPORT, @EXPORT_OK ] );
+
+use CPAN::Meta::Prereqs '2.132830';
+use CPAN::Meta::Requirements 2.121;
+use Module::Metadata 1.000023;
+
+sub _check_dep {
+	my ($reqs, $module, $dirs) = @_;
+
+	$module eq 'perl' and return ($reqs->accepts_module($module, $]) ? () : sprintf "Your Perl (%s) is not in the range '%s'", $], $reqs->requirements_for_module($module));
+
+	my $metadata = Module::Metadata->new_from_module($module, inc => $dirs);
+	return "Module '$module' is not installed" if not defined $metadata;
+
+	my $version = eval { $metadata->version };
+	return sprintf 'Installed version (%s) of %s is not in range \'%s\'',
+			(defined $version ? $version : 'undef'), $module, $reqs->requirements_for_module($module)
+		if not $reqs->accepts_module($module, $version || 0);
+	return;
+}
+
+sub _check_conflict {
+	my ($reqs, $module, $dirs) = @_;
+	my $metadata = Module::Metadata->new_from_module($module, inc => $dirs);
+	return if not defined $metadata;
+
+	my $version = eval { $metadata->version };
+	return sprintf 'Installed version (%s) of %s is in range \'%s\'',
+			(defined $version ? $version : 'undef'), $module, $reqs->requirements_for_module($module)
+		if $reqs->accepts_module($module, $version);
+	return;
+}
+
+sub requirements_for {
+	my ($meta, $phases, $type) = @_;
+	my $prereqs = ref($meta) eq 'CPAN::Meta' ? $meta->effective_prereqs : $meta;
+	return $prereqs->merged_requirements(ref($phases) ? $phases : [ $phases ], [ $type ]);
+}
+
+sub check_requirements {
+	my ($reqs, $type, $dirs) = @_;
+
+	return +{
+		map {
+			$_ => $type ne 'conflicts'
+				? scalar _check_dep($reqs, $_, $dirs)
+				: scalar _check_conflict($reqs, $_, $dirs)
+		} $reqs->required_modules
+	};
+}
+
+sub verify_dependencies {
+	my ($meta, $phases, $type, $dirs) = @_;
+	my $reqs = requirements_for($meta, $phases, $type);
+	my $issues = check_requirements($reqs, $type, $dirs);
+	return grep { defined } values %{ $issues };
+}
+
+1;
+
+#ABSTRACT: Verify requirements in a CPAN::Meta object
+
+__END__
+
+=pod
+
+=encoding UTF-8
+
+=head1 NAME
+
+CPAN::Meta::Check - Verify requirements in a CPAN::Meta object
+
+=head1 VERSION
+
+version 0.014
+
+=head1 SYNOPSIS
+
+ warn "$_\n" for verify_dependencies($meta, [qw/runtime build test/], 'requires');
+
+=head1 DESCRIPTION
+
+This module verifies if requirements described in a CPAN::Meta object are present.
+
+=head1 FUNCTIONS
+
+=head2 check_requirements($reqs, $type, $incdirs)
+
+This function checks if all dependencies in C<$reqs> (a L<CPAN::Meta::Requirements|CPAN::Meta::Requirements> object) are met, taking into account that 'conflicts' dependencies have to be checked in reverse. It returns a hash with the modules as keys and any problems as values; the value for a successfully found module will be undef. Modules are searched for in C<@$incdirs>, defaulting to C<@INC>.
+
+=head2 verify_dependencies($meta, $phases, $types, $incdirs)
+
+Check all requirements in C<$meta> for phases C<$phases> and type C<$type>. Modules are searched for in C<@$incdirs>, defaulting to C<@INC>. C<$meta> should be a L<CPAN::Meta::Prereqs> or L<CPAN::Meta> object.
+
+=head2 requirements_for($meta, $phases, $types)
+
+B<< This function is deprecated and may be removed at some point in the future, please use CPAN::Meta::Prereqs->merged_requirements instead. >>
+
+This function returns a unified L<CPAN::Meta::Requirements|CPAN::Meta::Requirements> object for all C<$type> requirements for C<$phases>. C<$phases> may be either one (scalar) value or an arrayref of valid values as defined by the L<CPAN::Meta spec|CPAN::Meta::Spec>. C<$type> must be a relationship as defined by the same spec. C<$meta> should be a L<CPAN::Meta::Prereqs> or L<CPAN::Meta> object.
+
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Test::CheckDeps|Test::CheckDeps>
+
+=item * L<CPAN::Meta|CPAN::Meta>
+
+=for comment # vi:noet:sts=2:sw=2:ts=2
+
+=back
+
+=head1 AUTHOR
+
+Leon Timmermans <leont@cpan.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2012 by Leon Timmermans.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut

database/perl/lib/CPAN/Meta/Feature.pm

@@ -0,0 +1,153 @@
+use 5.006;
+use strict;
+use warnings;
+package CPAN::Meta::Feature;
+
+our $VERSION = '2.150010';
+
+use CPAN::Meta::Prereqs;
+
+#pod =head1 DESCRIPTION
+#pod
+#pod A CPAN::Meta::Feature object describes an optional feature offered by a CPAN
+#pod distribution and specified in the distribution's F<META.json> (or F<META.yml>)
+#pod file.
+#pod
+#pod For the most part, this class will only be used when operating on the result of
+#pod the C<feature> or C<features> methods on a L<CPAN::Meta> object.
+#pod
+#pod =method new
+#pod
+#pod   my $feature = CPAN::Meta::Feature->new( $identifier => \%spec );
+#pod
+#pod This returns a new Feature object.  The C<%spec> argument to the constructor
+#pod should be the same as the value of the C<optional_feature> entry in the
+#pod distmeta.  It must contain entries for C<description> and C<prereqs>.
+#pod
+#pod =cut
+
+sub new {
+  my ($class, $identifier, $spec) = @_;
+
+  my %guts = (
+    identifier  => $identifier,
+    description => $spec->{description},
+    prereqs     => CPAN::Meta::Prereqs->new($spec->{prereqs}),
+  );
+
+  bless \%guts => $class;
+}
+
+#pod =method identifier
+#pod
+#pod This method returns the feature's identifier.
+#pod
+#pod =cut
+
+sub identifier  { $_[0]{identifier}  }
+
+#pod =method description
+#pod
+#pod This method returns the feature's long description.
+#pod
+#pod =cut
+
+sub description { $_[0]{description} }
+
+#pod =method prereqs
+#pod
+#pod This method returns the feature's prerequisites as a L<CPAN::Meta::Prereqs>
+#pod object.
+#pod
+#pod =cut
+
+sub prereqs     { $_[0]{prereqs} }
+
+1;
+
+# ABSTRACT: an optional feature provided by a CPAN distribution
+
+=pod
+
+=encoding UTF-8
+
+=head1 NAME
+
+CPAN::Meta::Feature - an optional feature provided by a CPAN distribution
+
+=head1 VERSION
+
+version 2.150010
+
+=head1 DESCRIPTION
+
+A CPAN::Meta::Feature object describes an optional feature offered by a CPAN
+distribution and specified in the distribution's F<META.json> (or F<META.yml>)
+file.
+
+For the most part, this class will only be used when operating on the result of
+the C<feature> or C<features> methods on a L<CPAN::Meta> object.
+
+=head1 METHODS
+
+=head2 new
+
+  my $feature = CPAN::Meta::Feature->new( $identifier => \%spec );
+
+This returns a new Feature object.  The C<%spec> argument to the constructor
+should be the same as the value of the C<optional_feature> entry in the
+distmeta.  It must contain entries for C<description> and C<prereqs>.
+
+=head2 identifier
+
+This method returns the feature's identifier.
+
+=head2 description
+
+This method returns the feature's long description.
+
+=head2 prereqs
+
+This method returns the feature's prerequisites as a L<CPAN::Meta::Prereqs>
+object.
+
+=head1 BUGS
+
+Please report any bugs or feature using the CPAN Request Tracker.
+Bugs can be submitted through the web interface at
+L<http://rt.cpan.org/Dist/Display.html?Queue=CPAN-Meta>
+
+When submitting a bug or request, please include a test-file or a patch to an
+existing test-file that illustrates the bug or desired feature.
+
+=head1 AUTHORS
+
+=over 4
+
+=item *
+
+David Golden <dagolden@cpan.org>
+
+=item *
+
+Ricardo Signes <rjbs@cpan.org>
+
+=item *
+
+Adam Kennedy <adamk@cpan.org>
+
+=back
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2010 by David Golden, Ricardo Signes, Adam Kennedy and Contributors.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut
+
+__END__
+
+
+# vim: ts=2 sts=2 sw=2 et :

database/perl/lib/CPAN/Meta/History.pm

@@ -0,0 +1,320 @@
+# vi:tw=72
+use 5.006;
+use strict;
+use warnings;
+package CPAN::Meta::History;
+
+our $VERSION = '2.150010';
+
+1;
+
+# ABSTRACT: history of CPAN Meta Spec changes
+
+__END__
+
+=pod
+
+=encoding UTF-8
+
+=head1 NAME
+
+CPAN::Meta::History - history of CPAN Meta Spec changes
+
+=head1 VERSION
+
+version 2.150010
+
+=head1 DESCRIPTION
+
+The CPAN Meta Spec has gone through several iterations.  It was
+originally written in HTML and later revised into POD (though published
+in HTML generated from the POD).  Fields were added, removed or changed,
+sometimes by design and sometimes to reflect real-world usage after the
+fact.
+
+This document reconstructs the history of the CPAN Meta Spec based on
+change logs, repository commit messages and the published HTML files.
+In some cases, particularly prior to version 1.2, the exact version
+when certain fields were introduced or changed is inconsistent between
+sources.  When in doubt, the published HTML files for versions 1.0 to
+1.4 as they existed when version 2 was developed are used as the
+definitive source.
+
+Starting with version 2, the specification document is part of the
+CPAN-Meta distribution and will be published on CPAN as
+L<CPAN::Meta::Spec>.
+
+Going forward, specification version numbers will be integers and
+decimal portions will correspond to a release date for the CPAN::Meta
+library.
+
+=head1 HISTORY
+
+=head2 Version 2
+
+April 2010
+
+=over
+
+=item *
+
+Revised spec examples as perl data structures rather than YAML
+
+=item *
+
+Switched to JSON serialization from YAML
+
+=item *
+
+Specified allowed version number formats
+
+=item *
+
+Replaced 'requires', 'build_requires', 'configure_requires',
+'recommends' and 'conflicts' with new 'prereqs' data structure divided
+by I<phase> (configure, build, test, runtime, etc.) and I<relationship>
+(requires, recommends, suggests, conflicts)
+
+=item *
+
+Added support for 'develop' phase for requirements for maintaining
+a list of authoring tools
+
+=item *
+
+Changed 'license' to a list and revised the set of valid licenses
+
+=item *
+
+Made 'dynamic_config' mandatory to reduce confusion
+
+=item *
+
+Changed 'resources' subkey 'repository' to a hash that clarifies
+repository type, url for browsing and url for checkout
+
+=item *
+
+Changed 'resources' subkey 'bugtracker' to a hash for either web
+or mailto resource
+
+=item *
+
+Changed specification of 'optional_features':
+
+=over
+
+=item *
+
+Added formal specification and usage guide instead of just example
+
+=item *
+
+Changed to use new prereqs data structure instead of individual keys
+
+=back
+
+=item *
+
+Clarified intended use of 'author' as generalized contact list
+
+=item *
+
+Added 'release_status' field to indicate stable, testing or unstable
+status to provide hints to indexers
+
+=item *
+
+Added 'description' field for a longer description of the distribution
+
+=item *
+
+Formalized use of "x_" or "X_" for all custom keys not listed in the
+official spec
+
+=back
+
+=head2 Version 1.4
+
+June 2008
+
+=over
+
+=item *
+
+Noted explicit support for 'perl' in prerequisites
+
+=item *
+
+Added 'configure_requires' prerequisite type
+
+=item *
+
+Changed 'optional_features'
+
+=over
+
+=item *
+
+Example corrected to show map of maps instead of list of maps
+(though descriptive text said 'map' even in v1.3)
+
+=item *
+
+Removed 'requires_packages', 'requires_os' and 'excluded_os'
+as valid subkeys
+
+=back
+
+=back
+
+=head2 Version 1.3
+
+November 2006
+
+=over
+
+=item *
+
+Added 'no_index' subkey 'directory' and removed 'dir' to match actual
+usage in the wild
+
+=item *
+
+Added a 'repository' subkey to 'resources'
+
+=back
+
+=head2 Version 1.2
+
+August 2005
+
+=over
+
+=item *
+
+Re-wrote and restructured spec in POD syntax
+
+=item *
+
+Changed 'name' to be mandatory
+
+=item *
+
+Changed 'generated_by' to be mandatory
+
+=item *
+
+Changed 'license' to be mandatory
+
+=item *
+
+Added version range specifications for prerequisites
+
+=item *
+
+Added required 'abstract' field
+
+=item *
+
+Added required 'author' field
+
+=item *
+
+Added required 'meta-spec' field to define 'version' (and 'url') of the
+CPAN Meta Spec used for metadata
+
+=item *
+
+Added 'provides' field
+
+=item *
+
+Added 'no_index' field and deprecated 'private' field.  'no_index'
+subkeys include 'file', 'dir', 'package' and 'namespace'
+
+=item *
+
+Added 'keywords' field
+
+=item *
+
+Added 'resources' field with subkeys 'homepage', 'license', and
+'bugtracker'
+
+=item *
+
+Added 'optional_features' field as an alternate under 'recommends'.
+Includes 'description', 'requires', 'build_requires', 'conflicts',
+'requires_packages', 'requires_os' and 'excluded_os' as valid subkeys
+
+=item *
+
+Removed 'license_uri' field
+
+=back
+
+=head2 Version 1.1
+
+May 2003
+
+=over
+
+=item *
+
+Changed 'version' to be mandatory
+
+=item *
+
+Added 'private' field
+
+=item *
+
+Added 'license_uri' field
+
+=back
+
+=head2 Version 1.0
+
+March 2003
+
+=over
+
+=item *
+
+Original release (in HTML format only)
+
+=item *
+
+Included 'name', 'version', 'license', 'distribution_type', 'requires',
+'recommends', 'build_requires', 'conflicts', 'dynamic_config',
+'generated_by'
+
+=back
+
+=head1 AUTHORS
+
+=over 4
+
+=item *
+
+David Golden <dagolden@cpan.org>
+
+=item *
+
+Ricardo Signes <rjbs@cpan.org>
+
+=item *
+
+Adam Kennedy <adamk@cpan.org>
+
+=back
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2010 by David Golden, Ricardo Signes, Adam Kennedy and Contributors.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut

database/perl/lib/CPAN/Meta/History/Meta_1_0.pod

@@ -0,0 +1,247 @@
+=for :stopwords DOAP RDF
+
+=head1 NAME
+
+CPAN::Meta::History::Meta_1_0 - Version 1.0 metadata specification for META.yml
+
+=head1 PREFACE
+
+This is a historical copy of the version 1.0 specification for F<META.yml>
+files, copyright by Ken Williams and licensed under the same terms as Perl
+itself.
+
+Modifications from the original:
+
+=over
+
+=item *
+
+Conversion from the original HTML to POD format
+
+=item *
+
+Include list of valid licenses from L<Module::Build> 0.17 rather than
+linking to the module, with minor updates to text and links to reflect
+versions at the time of publication.
+
+=item *
+
+Fixed some dead links to point to active resources.
+
+=back
+
+=head1 DESCRIPTION
+
+This document describes version 1.0 of the F<META.yml> specification.
+
+The META.yml file describes important properties of contributed Perl
+distributions such as the ones found on L<CPAN|http://www.cpan.org>.  It is
+typically created by tools like L<Module::Build> and L<ExtUtils::MakeMaker>.
+
+The fields in the F<META.yml> file are meant to be helpful to people
+maintaining module collections (like CPAN), for people writing
+installation tools (like L<CPAN> or L<CPANPLUS>), or just people who want to
+know some stuff about a distribution before downloading it and starting to
+install it.
+
+=head1 Format
+
+F<META.yml> files are written in the L<YAML|http://www.yaml.org/> format.  The
+reasons we chose YAML instead of, say, XML or Data::Dumper are discussed in
+L<this thread|http://www.nntp.perl.org/group/perl.makemaker/2002/04/msg406.html>
+on the MakeMaker mailing list.
+
+The first line of a F<META.yml> file should be a valid
+L<YAML document header|http://yaml.org/spec/history/2002-10-31.html#syntax-document>
+like C<"--- #YAML:1.0">
+
+=head1 Fields
+
+The rest of the META.yml file is one big YAML
+L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>,
+whose keys are described here.
+
+=over 4
+
+=item name
+
+Example: C<Module-Build>
+
+The name of the distribution.  Often created by taking the "main
+module" in the distribution and changing "::" to "-".  Sometimes it's
+completely different, however, as in the case of the
+L<libwww-perl|http://search.cpan.org/author/GAAS/libwww-perl/> distribution.
+
+=item version
+
+Example: C<0.16>
+
+The version of the distribution to which the META.yml file refers.
+
+=item license
+
+Example: C<perl>
+
+The license under which this distribution may be used and
+redistributed.
+
+Must be one of the following licenses:
+
+=over 4
+
+=item perl
+
+The distribution may be copied and redistributed under the same terms as perl
+itself (this is by far the most common licensing option for modules on CPAN).
+This is a dual license, in which the user may choose between either the GPL
+version 1 or the Artistic version 1 license.
+
+=item gpl
+
+The distribution is distributed under the terms of the GNU General Public
+License version 2 (L<http://opensource.org/licenses/GPL-2.0>).
+
+=item lgpl
+
+The distribution is distributed under the terms of the GNU Lesser General
+Public License version 2 (L<http://opensource.org/licenses/LGPL-2.1>).
+
+=item artistic
+
+The distribution is licensed under the Artistic License version 1, as specified
+by the Artistic file in the standard perl distribution
+(L<http://opensource.org/licenses/Artistic-Perl-1.0>).
+
+=item bsd
+
+The distribution is licensed under the BSD 3-Clause License
+(L<http://opensource.org/licenses/BSD-3-Clause>).
+
+=item open_source
+
+The distribution is licensed under some other Open Source Initiative-approved
+license listed at L<http://www.opensource.org/licenses/>.
+
+=item unrestricted
+
+The distribution is licensed under a license that is B<not> approved by
+L<www.opensource.org|http://www.opensource.org/> but that allows distribution
+without restrictions.
+
+=item restrictive
+
+The distribution may not be redistributed without special permission from the
+author and/or copyright holder.
+
+=back
+
+=item distribution_type
+
+Example: C<module>
+
+What kind of stuff is contained in this distribution.  Most things on
+CPAN are C<module>s (which can also mean a collection of
+modules), but some things are C<script>s.
+
+=item requires
+
+Example:
+
+  Data::Dumper: 0
+  File::Find: 1.03
+
+A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
+indicating the Perl modules this distribution requires for proper
+operation.  The keys are the module names, and the values are version
+specifications as described in the
+L<documentation for Module::Build's "requires" parameter|Module::Build::API/requires>.
+
+I<Note: the exact nature of the fancy specifications like
+C<< ">= 1.2, != 1.5, < 2.0" >> is subject to
+change.  Advance notice will be given here.  The simple specifications
+like C<"1.2"> will not change in format.>
+
+=item recommends
+
+Example:
+
+  Data::Dumper: 0
+  File::Find: 1.03
+
+A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
+indicating the Perl modules this distribution recommends for enhanced
+operation.
+
+=item build_requires
+
+Example:
+
+  Data::Dumper: 0
+  File::Find: 1.03
+
+A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
+indicating the Perl modules required for building and/or testing of
+this distribution.  These dependencies are not required after the
+module is installed.
+
+=item conflicts
+
+Example:
+
+  Data::Dumper: 0
+  File::Find: 1.03
+
+A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
+indicating the Perl modules that cannot be installed while this
+distribution is installed.  This is a pretty uncommon situation.
+
+=item dynamic_config
+
+Example: C<0>
+
+A boolean flag indicating whether a F<Build.PL> or
+F<Makefile.PL> (or similar) must be executed, or whether this
+module can be built, tested and installed solely from consulting its
+metadata file.  The main reason to set this to a true value if that
+your module performs some dynamic configuration (asking questions,
+sensing the environment, etc.) as part of its build/install process.
+
+Currently L<Module::Build> doesn't actually do anything with
+this flag - it's probably going to be up to higher-level tools like
+L<CPAN.pm|CPAN> to do something useful with it.  It can potentially
+bring lots of security, packaging, and convenience improvements.
+
+=item generated_by
+
+Example: C<Module::Build version 0.16>
+
+Indicates the tool that was used to create this F<META.yml> file.  It's
+good form to include both the name of the tool and its version, but
+this field is essentially opaque, at least for the moment.
+
+=back
+
+=head1 Related Projects
+
+=over 4
+
+=item DOAP
+
+An RDF vocabulary to describe software projects. L<http://usefulinc.com/doap>.
+
+=back
+
+=head1 History
+
+=over 4
+
+=item *
+
+B<March 14, 2003> (Pi day) - created version 1.0 of this document.
+
+=item *
+
+B<May 8, 2003> - added the "dynamic_config" field, which was missing from the
+initial version.
+
+=back

database/perl/lib/CPAN/Meta/History/Meta_1_1.pod

@@ -0,0 +1,309 @@
+=for :stopwords Ingy READMEs WTF licensure
+
+=head1 NAME
+
+CPAN::Meta::History::Meta_1_1 - Version 1.1 metadata specification for META.yml
+
+=head1 PREFACE
+
+This is a historical copy of the version 1.1 specification for F<META.yml>
+files, copyright by Ken Williams and licensed under the same terms as Perl
+itself.
+
+Modifications from the original:
+
+=over
+
+=item *
+
+Conversion from the original HTML to POD format
+
+=item *
+
+Include list of valid licenses from L<Module::Build> 0.18 rather than
+linking to the module, with minor updates to text and links to reflect
+versions at the time of publication.
+
+=item *
+
+Fixed some dead links to point to active resources.
+
+=back
+
+=head1 DESCRIPTION
+
+This document describes version 1.1 of the F<META.yml> specification.
+
+The F<META.yml> file describes important properties of contributed Perl
+distributions such as the ones found on L<CPAN|http://www.cpan.org>.  It is
+typically created by tools like L<Module::Build> and L<ExtUtils::MakeMaker>.
+
+The fields in the F<META.yml> file are meant to be helpful to people
+maintaining module collections (like CPAN), for people writing
+installation tools (like L<CPAN> or L<CPANPLUS>), or just people who want to
+know some stuff about a distribution before downloading it and starting to
+install it.
+
+=head1 Format
+
+F<META.yml> files are written in the L<YAML|http://www.yaml.org/> format.  The
+reasons we chose YAML instead of, say, XML or Data::Dumper are discussed in
+L<this thread|http://www.nntp.perl.org/group/perl.makemaker/2002/04/msg406.html>
+on the MakeMaker mailing list.
+
+The first line of a F<META.yml> file should be a valid
+L<YAML document header|http://yaml.org/spec/history/2002-10-31.html#syntax-document>
+like C<"--- #YAML:1.0">
+
+=head1 Fields
+
+The rest of the META.yml file is one big YAML
+L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>,
+whose keys are described here.
+
+=over 4
+
+=item name
+
+Example: C<Module-Build>
+
+The name of the distribution.  Often created by taking the "main
+module" in the distribution and changing "::" to "-".  Sometimes it's
+completely different, however, as in the case of the
+L<libwww-perl|http://search.cpan.org/author/GAAS/libwww-perl/> distribution.
+
+=item version
+
+Example: C<0.16>
+
+The version of the distribution to which the META.yml file refers.
+This is a mandatory field.
+
+The version is essentially an arbitrary string, but I<must> be
+only ASCII characters, and I<strongly should> be of the format
+integer-dot-digit-digit, i.e. C<25.57>, optionally followed by
+underscore-digit-digit, i.e. C<25.57_04>.
+
+The standard tools that deal with module distribution (PAUSE, CPAN,
+etc.) form an identifier for each distribution by joining the 'name'
+and 'version' attributes with a dash (C<->) character.  Tools
+who are prepared to deal with distributions that have no version
+numbers generally omit the dash as well.
+
+=item license
+
+Example: C<perl>
+
+a descriptive term for the licenses ... not authoritative, but must
+be consistent with licensure statements in the READMEs, documentation, etc.
+
+The license under which this distribution may be used and
+redistributed.
+
+Must be one of the following licenses:
+
+=over 4
+
+=item perl
+
+The distribution may be copied and redistributed under the same terms as perl
+itself (this is by far the most common licensing option for modules on CPAN).
+This is a dual license, in which the user may choose between either the GPL
+version 1 or the Artistic version 1 license.
+
+=item gpl
+
+The distribution is distributed under the terms of the GNU General Public
+License version 2 (L<http://opensource.org/licenses/GPL-2.0>).
+
+=item lgpl
+
+The distribution is distributed under the terms of the GNU Lesser General
+Public License version 2 (L<http://opensource.org/licenses/LGPL-2.1>).
+
+=item artistic
+
+The distribution is licensed under the Artistic License version 1, as specified
+by the Artistic file in the standard perl distribution
+(L<http://opensource.org/licenses/Artistic-Perl-1.0>).
+
+=item bsd
+
+The distribution is licensed under the BSD 3-Clause License
+(L<http://opensource.org/licenses/BSD-3-Clause>).
+
+=item open_source
+
+The distribution is licensed under some other Open Source Initiative-approved
+license listed at L<http://www.opensource.org/licenses/>.
+
+=item unrestricted
+
+The distribution is licensed under a license that is B<not> approved by
+L<www.opensource.org|http://www.opensource.org/> but that allows distribution
+without restrictions.
+
+=item restrictive
+
+The distribution may not be redistributed without special permission from the
+author and/or copyright holder.
+
+=back
+
+=item license_uri
+
+This should contain a URI where the exact terms of the license may be found.
+
+(change "unrestricted" to "redistributable"?)
+
+=item distribution_type
+
+Example: C<module>
+
+What kind of stuff is contained in this distribution.  Most things on
+CPAN are C<module>s (which can also mean a collection of
+modules), but some things are C<script>s.
+
+This field is basically meaningless, and tools (like Module::Build or
+MakeMaker) will likely stop generating it in the future.
+
+=item private
+
+WTF is going on here?
+
+index_ignore: any application that indexes the contents of
+distributions (PAUSE, search.cpan.org) ought to ignore the items
+(packages, files, directories, namespace hierarchies).
+
+=item requires
+
+Example:
+
+  Data::Dumper: 0
+  File::Find: 1.03
+
+A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
+indicating the Perl modules this distribution requires for proper
+operation.  The keys are the module names, and the values are version
+specifications as described in the
+L<documentation for Module::Build's "requires" parameter|Module::Build::API/requires>.
+
+I<Note: the exact nature of the fancy specifications like
+C<< ">= 1.2, != 1.5, < 2.0" >> is subject to
+change.  Advance notice will be given here.  The simple specifications
+like C<"1.2"> will not change in format.>
+
+=item recommends
+
+Example:
+
+  Data::Dumper: 0
+  File::Find: 1.03
+
+A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
+indicating the Perl modules this distribution recommends for enhanced
+operation.
+
+=item build_requires
+
+Example:
+
+  Data::Dumper: 0
+  File::Find: 1.03
+
+A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
+indicating the Perl modules required for building and/or testing of
+this distribution.  These dependencies are not required after the
+module is installed.
+
+=item conflicts
+
+Example:
+
+  Data::Dumper: 0
+  File::Find: 1.03
+
+A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
+indicating the Perl modules that cannot be installed while this
+distribution is installed.  This is a pretty uncommon situation.
+
+- possibly separate out test-time prereqs, complications include: can
+tests be meaningfully preserved for later running?  are test-time
+prereqs in addition to build-time, or exclusive?
+
+- make official location for installed *distributions*, which can
+contain tests, etc.
+
+=item dynamic_config
+
+Example: C<0>
+
+A boolean flag indicating whether a F<Build.PL> or
+F<Makefile.PL> (or similar) must be executed, or whether this
+module can be built, tested and installed solely from consulting its
+metadata file.  The main reason to set this to a true value if that
+your module performs some dynamic configuration (asking questions,
+sensing the environment, etc.) as part of its build/install process.
+
+Currently L<Module::Build> doesn't actually do anything with
+this flag - it's probably going to be up to higher-level tools like
+L<CPAN.pm|CPAN> to do something useful with it.  It can potentially
+bring lots of security, packaging, and convenience improvements.
+
+=item generated_by
+
+Example: C<Module::Build version 0.16>
+
+Indicates the tool that was used to create this F<META.yml> file.  It's
+good form to include both the name of the tool and its version, but
+this field is essentially opaque, at least for the moment.
+
+=back
+
+=head2 Ingy's suggestions
+
+=over 4
+
+=item short_description
+
+add as field, containing abstract, maximum 80 characters, suggested minimum 40 characters
+
+=item description
+
+long version of abstract, should add?
+
+=item maturity
+
+alpha, beta, gamma, mature, stable
+
+=item author_id, owner_id
+
+=item categorization, keyword, chapter_id
+
+=item URL for further information
+
+could default to search.cpan.org on PAUSE
+
+=item namespaces
+
+can be specified for single elements by prepending
+dotted-form, i.e. "com.example.my_application.my_property".  Default
+namespace for META.yml is probably "org.cpan.meta_author" or
+something.  Precedent for this is Apple's Carbon namespaces, I think.
+
+=back
+
+=head1 History
+
+=over 4
+
+=item *
+
+B<March 14, 2003> (Pi day) - created version 1.0 of this document.
+
+=item *
+
+B<May 8, 2003> - added the "dynamic_config" field, which was missing from the
+initial version.
+
+=back

database/perl/lib/CPAN/Meta/History/Meta_1_2.pod

@@ -0,0 +1,712 @@
+=for :stopwords MailingList RWS subcontext
+
+=head1 NAME
+
+CPAN::Meta::History::Meta_1_2 - Version 1.2 metadata specification for META.yml
+
+=head1 PREFACE
+
+This is a historical copy of the version 1.2 specification for F<META.yml>
+files, copyright by Ken Williams and licensed under the same terms as Perl
+itself.
+
+Modifications from the original:
+
+=over
+
+=item *
+
+Various spelling corrections
+
+=item *
+
+Include list of valid licenses from L<Module::Build> 0.2611 rather than
+linking to the module, with minor updates to text and links to reflect
+versions at the time of publication.
+
+=item *
+
+Fixed some dead links to point to active resources.
+
+=back
+
+=head1 SYNOPSIS
+
+ --- #YAML:1.0
+ name: Module-Build
+ abstract: Build and install Perl modules
+ version: 0.20
+ author:
+   - Ken Williams <kwilliams@cpan.org>
+ license: perl
+ distribution_type: module
+ requires:
+   Config: 0
+   Cwd: 0
+   Data::Dumper: 0
+   ExtUtils::Install: 0
+   File::Basename: 0
+   File::Compare: 0
+   File::Copy: 0
+   File::Find: 0
+   File::Path: 0
+   File::Spec: 0
+   IO::File: 0
+   perl: 5.005_03
+ recommends:
+   Archive::Tar: 1.00
+   ExtUtils::Install: 0.3
+   ExtUtils::ParseXS: 2.02
+   Pod::Text: 0
+   YAML: 0.35
+ build_requires:
+   Test: 0
+ urls:
+   license: http://dev.perl.org/licenses/
+ meta-spec:
+   version: 1.2
+   url: http://module-build.sourceforge.net/META-spec-v1.2.html
+ generated_by: Module::Build version 0.20
+
+=head1 DESCRIPTION
+
+This document describes version 1.2 of the F<META.yml> specification.
+
+The F<META.yml> file describes important properties of contributed
+Perl distributions such as the ones found on CPAN.  It is typically
+created by tools like Module::Build, Module::Install, and
+ExtUtils::MakeMaker.
+
+The fields in the F<META.yml> file are meant to be helpful for people
+maintaining module collections (like CPAN), for people writing
+installation tools (like CPAN.pm or CPANPLUS), or just for people who
+want to know some stuff about a distribution before downloading it and
+starting to install it.
+
+I<Note: The latest stable version of this specification can always be
+found at L<http://module-build.sourceforge.net/META-spec-current.html>,
+and the latest development version (which may include things that
+won't make it into the stable version can always be found at
+L<http://module-build.sourceforge.net/META-spec-blead.html>.>
+
+=head1 FORMAT
+
+F<META.yml> files are written in the YAML format (see
+L<http://www.yaml.org/>).
+
+See the following links to learn why we chose YAML instead of, say,
+XML or Data::Dumper:
+
+=over 4
+
+=item *
+
+L<Module::Build design plans|http://www.nntp.perl.org/group/perl.makemaker/2002/04/msg407.html>
+
+=item *
+
+L<Not keen on YAML|http://www.nntp.perl.org/group/perl.module-authors/2003/11/msg1353.html>
+
+=item *
+
+L<META Concerns|http://www.nntp.perl.org/group/perl.module-authors/2003/11/msg1385.html>
+
+=back
+
+=head1 TERMINOLOGY
+
+=over 4
+
+=item distribution
+
+This is the primary object described by the F<META.yml>
+specification. In the context of this document it usually refers to a
+collection of modules, scripts, and/or documents that are distributed
+for other developers to use.
+
+=item module
+
+This refers to a reusable library of code typically contained in a
+single file. Currently, we primarily talk of perl modules, but this
+specification should be open enough to apply to other languages as
+well (ex. python, ruby).
+
+=back
+
+=head1 VERSION SPECIFICATIONS
+
+Some fields require a version specification (ex. L</requires>,
+L</recommends>, L</build_requires>, etc.).  This section details the
+version specifications that are currently supported.
+
+If a single version is listed, then that version is considered to be
+the minimum version supported.
+
+If 0 is given as the version number, then any version is supported.
+
+Additionally, for more complicated requirements, the specification
+supports a list of versions, each of which may be optionally preceded
+by a relational operator.
+
+Supported operators include E<lt> (less than), E<lt>= (less than or
+equal), E<gt> (greater than), E<gt>= (greater than or equal), == (equal), and !=
+(not equal).
+
+If a list is given then it is evaluated from left to right so that any
+specifications in the list that conflict with a previous specification
+are overridden by the later.
+
+Examples:
+
+ >= 1.2, != 1.5, < 2.0
+
+Any version from version 1.2 onward, except version 1.5, that also
+precedes version 2.0.
+
+=head1 HEADER
+
+The first line of a F<META.yml> file should be a valid YAML document
+header like C<"--- #YAML:1.0">.
+
+=head1 FIELDS
+
+The rest of the F<META.yml> file is one big YAML mapping whose keys
+are described here.
+
+=head2 meta-spec
+
+Example:
+
+ meta-spec:
+   version: 1.2
+   url: http://module-build.sourceforge.net/META-spec-v1.2.html
+
+(Spec 1.1) [required] {URL} This field indicates the location of the
+version of the META.yml specification used.
+
+=head2 name
+
+Example:
+
+  name: Module-Build
+
+(Spec 1.0) [required] {string} The name of the distribution which is often
+created by taking the "main module" in the distribution and changing
+"::" to "-".  Sometimes it's completely different, however, as in the
+case of the libwww-perl distribution (see
+L<http://search.cpan.org/author/GAAS/libwww-perl/>).
+
+=head2 version
+
+Example:
+
+  version: 0.20
+
+(Spec 1.0) [required] {version} The version of the distribution to which the
+F<META.yml> file refers.
+
+=head2 abstract
+
+Example:
+
+  abstract: Build and install Perl modules.
+
+(Spec 1.1) [required] {string} A short description of the purpose of the
+distribution.
+
+=head2 author
+
+Example:
+
+  author:
+    - Ken Williams <kwilliams@cpan.org>
+
+(Spec 1.1) [required] {list of strings} A YAML sequence indicating the author(s) of the
+distribution. The preferred form is author-name <email-address>.
+
+=head2 license
+
+Example:
+
+  license: perl
+
+(Spec 1.0) [required] {string} The license under which this distribution may be
+used and redistributed.
+
+Must be one of the following licenses:
+
+=over 4
+
+=item perl
+
+The distribution may be copied and redistributed under the same terms as perl
+itself (this is by far the most common licensing option for modules on CPAN).
+This is a dual license, in which the user may choose between either the GPL
+version 1 or the Artistic version 1 license.
+
+=item gpl
+
+The distribution is distributed under the terms of the GNU General Public
+License version 2 (L<http://opensource.org/licenses/GPL-2.0>).
+
+=item lgpl
+
+The distribution is distributed under the terms of the GNU Lesser General
+Public License version 2 (L<http://opensource.org/licenses/LGPL-2.1>).
+
+=item artistic
+
+The distribution is licensed under the Artistic License version 1, as specified
+by the Artistic file in the standard perl distribution
+(L<http://opensource.org/licenses/Artistic-Perl-1.0>).
+
+=item bsd
+
+The distribution is licensed under the BSD 3-Clause License
+(L<http://opensource.org/licenses/BSD-3-Clause>).
+
+=item open_source
+
+The distribution is licensed under some other Open Source Initiative-approved
+license listed at L<http://www.opensource.org/licenses/>.
+
+=item unrestricted
+
+The distribution is licensed under a license that is B<not> approved by
+L<www.opensource.org|http://www.opensource.org/> but that allows distribution
+without restrictions.
+
+=item restrictive
+
+The distribution may not be redistributed without special permission from the
+author and/or copyright holder.
+
+=back
+
+=head2 distribution_type
+
+Example:
+
+  distribution_type: module
+
+(Spec 1.0) [optional] {string} What kind of stuff is contained in this
+distribution.  Most things on CPAN are C<module>s (which can also mean
+a collection of modules), but some things are C<script>s.
+
+Unfortunately this field is basically meaningless, since many
+distributions are hybrids of several kinds of things, or some new
+thing, or subjectively different in focus depending on who's using
+them.  Tools like Module::Build and MakeMaker will likely stop
+generating this field.
+
+=head2 requires
+
+Example:
+
+  requires:
+    Data::Dumper: 0
+    File::Find: 1.03
+
+(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules this
+distribution requires for proper operation.  The keys are the module
+names, and the values are version specifications as described in
+L<Module::Build> for the "requires" parameter.
+
+=head2 recommends
+
+Example:
+
+  recommends:
+    Data::Dumper: 0
+    File::Find: 1.03
+
+(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules this
+distribution recommends for enhanced operation.
+
+I<ALTERNATIVE: It may be desirable to present to the user which
+features depend on which modules so they can make an informed
+decision about which recommended modules to install.>
+
+Example:
+
+  optional_features:
+  - foo:
+      description: Provides the ability to blah.
+      requires:
+        Data::Dumper: 0
+        File::Find: 1.03
+  - bar:
+      description: This feature is not available on this platform.
+      excludes_os: MSWin32
+
+I<(Spec 1.1) [optional] {map} A YAML sequence of names for optional features
+which are made available when its requirements are met. For each
+feature a description is provided along with any of L</requires>,
+L</build_requires>, L</conflicts>, C<requires_packages>,
+C<requires_os>, and C<excludes_os> which have the same meaning in
+this subcontext as described elsewhere in this document.>
+
+=head2 build_requires
+
+Example:
+
+  build_requires:
+    Data::Dumper: 0
+    File::Find: 1.03
+
+(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules
+required for building and/or testing of this distribution.  These
+dependencies are not required after the module is installed.
+
+=head2 conflicts
+
+Example:
+
+  conflicts:
+    Data::Dumper: 0
+    File::Find: 1.03
+
+(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules that
+cannot be installed while this distribution is installed.  This is a
+pretty uncommon situation.
+
+=head2 dynamic_config
+
+Example:
+
+  dynamic_config: 0
+
+(Spec 1.0) [optional] {boolean} A boolean flag indicating whether a F<Build.PL>
+or F<Makefile.PL> (or similar) must be executed when building this
+distribution, or whether it can be built, tested and installed solely
+from consulting its
+metadata file.  The main reason to set this to a true value if that
+your module performs some dynamic configuration (asking questions,
+sensing the environment, etc.) as part of its build/install process.
+
+Currently Module::Build doesn't actually do anything with this flag
+- it's probably going to be up to higher-level tools like CPAN
+to do something useful with it.  It can potentially bring lots of
+security, packaging, and convenience improvements.
+
+If this field is omitted, it defaults to 1 (true).
+
+=head2 private
+
+I<(Deprecated)> (Spec 1.0) [optional] {map} This field has been renamed to
+L</no_index>.  See below.
+
+=head2 provides
+
+Example:
+
+  provides:
+    Foo::Bar:
+      file: lib/Foo/Bar.pm
+      version: 0.27_02
+    Foo::Bar::Blah:
+      file: lib/Foo/Bar/Blah.pm
+    Foo::Bar::Baz:
+      file: lib/Foo/Bar/Baz.pm
+      version: 0.3
+
+(Spec 1.1) [optional] {map} A YAML mapping that describes all packages
+provided by this distribution.  This information can be (and, in some
+cases, is) used by distribution and automation mechanisms like PAUSE,
+CPAN, and search.cpan.org to build indexes saying in which
+distribution various packages can be found.
+
+When using tools like L<Module::Build> that can generate the
+C<provides> mapping for your distribution automatically, make sure you
+examine what it generates to make sure it makes sense - indexers will
+usually trust the C<provides> field if it's present, rather than
+scanning through the distribution files themselves to figure out
+packages and versions.  This is a good thing, because it means you can
+use the C<provides> field to tell the indexers precisely what you want
+indexed about your distribution, rather than relying on them to
+essentially guess what you want indexed.
+
+=head2 no_index
+
+Example:
+
+  no_index:
+    file:
+    - My/Module.pm
+    dir:
+    - My/Private
+    package:
+    - My::Module::Stuff
+    namespace:
+    - My::Module::Stuff
+
+(Spec 1.1) [optional] {map} A YAML mapping that describes any files,
+directories, packages, and namespaces that are private
+(i.e. implementation artifacts) that are not of interest to searching
+and indexing tools.  This is useful when no C<provides> field is
+present.
+
+I<(Note: I'm not actually sure who looks at this field, or exactly
+what they do with it.  This spec could be off in some way from actual
+usage.)>
+
+=head3 file
+
+(Spec 1.1) [optional] Exclude any listed file(s).
+
+=head3 dir
+
+(Spec 1.1) [optional] Exclude anything below the listed
+directory(ies).
+
+=head3 package
+
+(Spec 1.1) [optional] Exclude the listed package(s).
+
+=head3 namespace
+
+(Spec 1.1) [optional] Excludes anything below the listed namespace(s),
+but I<not> the listed namespace(s) its self.
+
+=head2 keywords
+
+Example:
+
+  keywords:
+    - make
+    - build
+    - install
+
+(Spec 1.1) [optional] {list} A sequence of keywords/phrases that describe
+this distribution.
+
+=head2 resources
+
+Example:
+
+  resources:
+    license: http://dev.perl.org/licenses/
+    homepage: http://sourceforge.net/projects/module-build
+    bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build
+    MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general
+
+(Spec 1.1) [optional] {map} A mapping of any URL resources related to
+this distribution.  All-lower-case keys, such as C<homepage>,
+C<license>, and C<bugtracker>, are reserved by this specification, as
+they have "official" meanings defined here in this specification.  If
+you'd like to add your own "special" entries (like the "MailingList"
+entry above), use at least one upper-case letter.
+
+The current set of official keys is:
+
+=over 2
+
+=item homepage
+
+The official home of this project on the web.
+
+=item license
+
+An URL for an official statement of this distribution's license.
+
+=item bugtracker
+
+An URL for a bug tracker (e.g. Bugzilla or RT queue) for this project.
+
+=back
+
+
+=head2 generated_by
+
+Example:
+
+  generated_by: Module::Build version 0.20
+
+(Spec 1.0) [required] {string} Indicates the tool that was used to create this
+F<META.yml> file.  It's good form to include both the name of the tool
+and its version, but this field is essentially opaque, at least for
+the moment. If F<META.yml> was generated by hand, it is suggested that
+the author be specified here.
+
+[Note: My F<meta_stats.pl> script which I use to gather statistics
+regarding F<META.yml> usage prefers the form listed above, i.e. it
+splits on /\s+version\s+/ taking the first field as the name of the
+tool that generated the file and the second field as version of that
+tool. RWS]
+
+=head1 SEE ALSO
+
+L<CPAN|http://www.cpan.org/>
+
+L<CPAN.pm|CPAN>
+
+L<CPANPLUS>
+
+L<Data::Dumper>
+
+L<ExtUtils::MakeMaker>
+
+L<Module::Build>
+
+L<Module::Install>
+
+L<XML|http://www.w3.org/XML/>
+
+L<YAML|http://www.yaml.org/>
+
+=head1 HISTORY
+
+=over 4
+
+=item March 14, 2003 (Pi day)
+
+=over 2
+
+=item *
+
+Created version 1.0 of this document.
+
+=back
+
+=item May 8, 2003
+
+=over 2
+
+=item *
+
+Added the L</dynamic_config> field, which was missing from the initial
+version.
+
+=back
+
+=item November 13, 2003
+
+=over 2
+
+=item *
+
+Added more YAML rationale articles.
+
+=item *
+
+Fixed existing link to YAML discussion thread to point to new
+L<http://nntp.x.perl.org/group/> site.
+
+=item *
+
+Added and deprecated the L</private> field.
+
+=item *
+
+Added L</abstract>, C<configure>, C<requires_packages>,
+C<requires_os>, C<excludes_os>, and L</no_index> fields.
+
+=item *
+
+Bumped version.
+
+=back
+
+=item November 16, 2003
+
+=over 2
+
+=item *
+
+Added C<generation>, C<authored_by> fields.
+
+=item *
+
+Add alternative proposal to the L</recommends> field.
+
+=item *
+
+Add proposal for a C<requires_build_tools> field.
+
+=back
+
+=item December 9, 2003
+
+=over 2
+
+=item *
+
+Added link to latest version of this specification on CPAN.
+
+=item *
+
+Added section L</"VERSION SPECIFICATIONS">.
+
+=item *
+
+Chang name from Module::Build::META-spec to CPAN::META::Specification.
+
+=item *
+
+Add proposal for C<auto_regenerate> field.
+
+=back
+
+=item December 15, 2003
+
+=over 2
+
+=item *
+
+Add C<index> field as a compliment to L</no_index>
+
+=item *
+
+Add L</keywords> field as a means to aid searching distributions.
+
+=item *
+
+Add L</TERMINOLOGY> section to explain certain terms that may be
+ambiguous.
+
+=back
+
+=item July 26, 2005
+
+=over 2
+
+=item *
+
+Removed a bunch of items (generation, requires_build_tools,
+requires_packages, configure, requires_os, excludes_os,
+auto_regenerate) that have never actually been supported, but were
+more like records of brainstorming.
+
+=item *
+
+Changed C<authored_by> to L</author>, since that's always been what
+it's actually called in actual F<META.yml> files.
+
+=item *
+
+Added the "==" operator to the list of supported version-checking
+operators.
+
+=item *
+
+Noted that the L</distribution_type> field is basically meaningless,
+and shouldn't really be used.
+
+=item *
+
+Clarified L</dynamic_config> a bit.
+
+=back
+
+=item August 23, 2005
+
+=over 2
+
+=item *
+
+Removed the name C<CPAN::META::Specification>, since that implies a
+module that doesn't actually exist.
+
+=back
+
+=back

database/perl/lib/CPAN/Meta/History/Meta_1_3.pod

@@ -0,0 +1,741 @@
+=for :stopwords MailingList PODs RWS subcontext
+
+=head1 NAME
+
+CPAN::Meta::History::Meta_1_3 - Version 1.3 metadata specification for META.yml
+
+=head1 PREFACE
+
+This is a historical copy of the version 1.3 specification for F<META.yml>
+files, copyright by Ken Williams and licensed under the same terms as Perl
+itself.
+
+Modifications from the original:
+
+=over
+
+=item *
+
+Various spelling corrections
+
+=item *
+
+Include list of valid licenses from L<Module::Build> 0.2805 rather than
+linking to the module, with minor updates to text and links to reflect
+versions at the time of publication.
+
+=item *
+
+Fixed some dead links to point to active resources.
+
+=back
+
+=head1 SYNOPSIS
+
+ --- #YAML:1.0
+ name: Module-Build
+ abstract: Build and install Perl modules
+ version: 0.20
+ author:
+   - Ken Williams <kwilliams@cpan.org>
+ license: perl
+ distribution_type: module
+ requires:
+   Config: 0
+   Cwd: 0
+   Data::Dumper: 0
+   ExtUtils::Install: 0
+   File::Basename: 0
+   File::Compare: 0
+   File::Copy: 0
+   File::Find: 0
+   File::Path: 0
+   File::Spec: 0
+   IO::File: 0
+   perl: 5.005_03
+ recommends:
+   Archive::Tar: 1.00
+   ExtUtils::Install: 0.3
+   ExtUtils::ParseXS: 2.02
+   Pod::Text: 0
+   YAML: 0.35
+ build_requires:
+   Test: 0
+ urls:
+   license: http://dev.perl.org/licenses/
+ meta-spec:
+   version: 1.3
+   url: http://module-build.sourceforge.net/META-spec-v1.3.html
+ generated_by: Module::Build version 0.20
+
+=head1 DESCRIPTION
+
+This document describes version 1.3 of the F<META.yml> specification.
+
+The F<META.yml> file describes important properties of contributed
+Perl distributions such as the ones found on CPAN.  It is typically
+created by tools like Module::Build, Module::Install, and
+ExtUtils::MakeMaker.
+
+The fields in the F<META.yml> file are meant to be helpful for people
+maintaining module collections (like CPAN), for people writing
+installation tools (like CPAN.pm or CPANPLUS), or just for people who
+want to know some stuff about a distribution before downloading it and
+starting to install it.
+
+I<Note: The latest stable version of this specification can always be
+found at L<http://module-build.sourceforge.net/META-spec-current.html>,
+and the latest development version (which may include things that
+won't make it into the stable version) can always be found at
+L<http://module-build.sourceforge.net/META-spec-blead.html>.>
+
+=head1 FORMAT
+
+F<META.yml> files are written in the YAML format (see
+L<http://www.yaml.org/>).
+
+See the following links to learn why we chose YAML instead of, say,
+XML or Data::Dumper:
+
+=over 4
+
+=item *
+
+L<Module::Build design plans|http://www.nntp.perl.org/group/perl.makemaker/2002/04/msg407.html>
+
+=item *
+
+L<Not keen on YAML|http://www.nntp.perl.org/group/perl.module-authors/2003/11/msg1353.html>
+
+=item *
+
+L<META Concerns|http://www.nntp.perl.org/group/perl.module-authors/2003/11/msg1385.html>
+
+=back
+
+=head1 TERMINOLOGY
+
+=over 4
+
+=item distribution
+
+This is the primary object described by the F<META.yml>
+specification. In the context of this document it usually refers to a
+collection of modules, scripts, and/or documents that are distributed
+together for other developers to use.  Examples of distributions are
+C<Class-Container>, C<libwww-perl>, or C<DBI>.
+
+=item module
+
+This refers to a reusable library of code typically contained in a
+single file. Currently, we primarily talk of perl modules, but this
+specification should be open enough to apply to other languages as
+well (ex. python, ruby).  Examples of modules are C<Class::Container>,
+C<LWP::Simple>, or C<DBD::File>.
+
+=back
+
+=head1 HEADER
+
+The first line of a F<META.yml> file should be a valid YAML document
+header like C<"--- #YAML:1.0">.
+
+=head1 FIELDS
+
+The rest of the F<META.yml> file is one big YAML mapping whose keys
+are described here.
+
+=head2 meta-spec
+
+Example:
+
+ meta-spec:
+   version: 1.3
+   url: http://module-build.sourceforge.net/META-spec-v1.3.html
+
+(Spec 1.1) [required] {URL} This field indicates the location of the
+version of the META.yml specification used.
+
+=head2 name
+
+Example:
+
+  name: Module-Build
+
+(Spec 1.0) [required] {string} The name of the distribution which is often
+created by taking the "main module" in the distribution and changing
+"::" to "-".  Sometimes it's completely different, however, as in the
+case of the libwww-perl distribution (see
+L<http://search.cpan.org/dist/libwww-perl/>).
+
+=head2 version
+
+Example:
+
+  version: 0.20
+
+(Spec 1.0) [required] {version} The version of the distribution to which the
+F<META.yml> file refers.
+
+=head2 abstract
+
+Example:
+
+  abstract: Build and install Perl modules.
+
+(Spec 1.1) [required] {string} A short description of the purpose of the
+distribution.
+
+=head2 author
+
+Example:
+
+  author:
+    - Ken Williams <kwilliams@cpan.org>
+
+(Spec 1.1) [required] {list of strings} A YAML sequence indicating the author(s) of the
+distribution. The preferred form is author-name <email-address>.
+
+=head2 license
+
+Example:
+
+  license: perl
+
+(Spec 1.0) [required] {string} The license under which this distribution may be
+used and redistributed.
+
+Must be one of the following licenses:
+
+=over 4
+
+=item apache
+
+The distribution is licensed under the Apache Software License version 1.1
+(L<http://opensource.org/licenses/Apache-1.1>).
+
+=item artistic
+
+The distribution is licensed under the Artistic License version 1, as specified
+by the Artistic file in the standard perl distribution
+(L<http://opensource.org/licenses/Artistic-Perl-1.0>).
+
+=item bsd
+
+The distribution is licensed under the BSD 3-Clause License
+(L<http://opensource.org/licenses/BSD-3-Clause>).
+
+=item gpl
+
+The distribution is distributed under the terms of the GNU General Public
+License version 2 (L<http://opensource.org/licenses/GPL-2.0>).
+
+=item lgpl
+
+The distribution is distributed under the terms of the GNU Lesser General
+Public License version 2 (L<http://opensource.org/licenses/LGPL-2.1>).
+
+=item mit
+
+The distribution is licensed under the MIT License
+(L<http://opensource.org/licenses/MIT>).
+
+=item mozilla
+
+The distribution is licensed under the Mozilla Public License.
+(L<http://opensource.org/licenses/MPL-1.0> or
+L<http://opensource.org/licenses/MPL-1.1>)
+
+=item open_source
+
+The distribution is licensed under some other Open Source Initiative-approved
+license listed at L<http://www.opensource.org/licenses/>.
+
+=item perl
+
+The distribution may be copied and redistributed under the same terms as perl
+itself (this is by far the most common licensing option for modules on CPAN).
+This is a dual license, in which the user may choose between either the GPL
+version 1 or the Artistic version 1 license.
+
+=item restrictive
+
+The distribution may not be redistributed without special permission from the
+author and/or copyright holder.
+
+=item unrestricted
+
+The distribution is licensed under a license that is not approved by
+L<www.opensource.org|http://www.opensource.org/> but that allows distribution
+without restrictions.
+
+=back
+
+=head2 distribution_type
+
+Example:
+
+  distribution_type: module
+
+(Spec 1.0) [optional] {string} What kind of stuff is contained in this
+distribution.  Most things on CPAN are C<module>s (which can also mean
+a collection of modules), but some things are C<script>s.
+
+Unfortunately this field is basically meaningless, since many
+distributions are hybrids of several kinds of things, or some new
+thing, or subjectively different in focus depending on who's using
+them.  Tools like Module::Build and MakeMaker will likely stop
+generating this field.
+
+=head2 requires
+
+Example:
+
+  requires:
+    Data::Dumper: 0
+    File::Find: 1.03
+
+(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules this
+distribution requires for proper operation.  The keys are the module
+names, and the values are version specifications as described in
+L</"VERSION SPECIFICATIONS">.
+
+=head2 recommends
+
+Example:
+
+  recommends:
+    Data::Dumper: 0
+    File::Find: 1.03
+
+(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules
+this distribution recommends for enhanced operation.  The keys are the
+module names, and the values are version specifications as described
+in L</"VERSION SPECIFICATIONS">.
+
+
+
+I<ALTERNATIVE: It may be desirable to present to the user which
+features depend on which modules so they can make an informed decision
+about which recommended modules to install.>
+
+Example:
+
+  optional_features:
+  - foo:
+      description: Provides the ability to blah.
+      requires:
+        Data::Dumper: 0
+        File::Find: 1.03
+  - bar:
+      description: This feature is not available on this platform.
+      excludes_os: MSWin32
+
+I<(Spec 1.1) [optional] {map} A YAML sequence of names for optional features
+which are made available when its requirements are met. For each
+feature a description is provided along with any of L</requires>,
+L</build_requires>, L</conflicts>, C<requires_packages>,
+C<requires_os>, and C<excludes_os> which have the same meaning in
+this subcontext as described elsewhere in this document.>
+
+=head2 build_requires
+
+Example:
+
+  build_requires:
+    Data::Dumper: 0
+    File::Find: 1.03
+
+(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules
+required for building and/or testing of this distribution.  The keys
+are the module names, and the values are version specifications as
+described in L</"VERSION SPECIFICATIONS">.  These dependencies are not
+required after the module is installed.
+
+=head2 conflicts
+
+Example:
+
+  conflicts:
+    Data::Dumper: 0
+    File::Find: 1.03
+
+(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules that
+cannot be installed while this distribution is installed.  This is a
+pretty uncommon situation.  The keys for C<conflicts> are the module
+names, and the values are version specifications as described in
+L</"VERSION SPECIFICATIONS">.
+
+
+=head2 dynamic_config
+
+Example:
+
+  dynamic_config: 0
+
+(Spec 1.0) [optional] {boolean} A boolean flag indicating whether a F<Build.PL>
+or F<Makefile.PL> (or similar) must be executed when building this
+distribution, or whether it can be built, tested and installed solely
+from consulting its
+metadata file.  The main reason to set this to a true value is that
+your module performs some dynamic configuration (asking questions,
+sensing the environment, etc.) as part of its build/install process.
+
+Currently Module::Build doesn't actually do anything with this flag
+- it's probably going to be up to higher-level tools like CPAN
+to do something useful with it.  It can potentially bring lots of
+security, packaging, and convenience improvements.
+
+If this field is omitted, it defaults to 1 (true).
+
+=head2 private
+
+I<(Deprecated)> (Spec 1.0) [optional] {map} This field has been renamed to
+L</no_index>.  See below.
+
+=head2 provides
+
+Example:
+
+  provides:
+    Foo::Bar:
+      file: lib/Foo/Bar.pm
+      version: 0.27_02
+    Foo::Bar::Blah:
+      file: lib/Foo/Bar/Blah.pm
+    Foo::Bar::Baz:
+      file: lib/Foo/Bar/Baz.pm
+      version: 0.3
+
+(Spec 1.1) [optional] {map} A YAML mapping that describes all packages
+provided by this distribution.  This information can be (and, in some
+cases, is) used by distribution and automation mechanisms like PAUSE,
+CPAN, and search.cpan.org to build indexes saying in which
+distribution various packages can be found.
+
+When using tools like L<Module::Build> that can generate the
+C<provides> mapping for your distribution automatically, make sure you
+examine what it generates to make sure it makes sense - indexers will
+usually trust the C<provides> field if it's present, rather than
+scanning through the distribution files themselves to figure out
+packages and versions.  This is a good thing, because it means you can
+use the C<provides> field to tell the indexers precisely what you want
+indexed about your distribution, rather than relying on them to
+essentially guess what you want indexed.
+
+=head2 no_index
+
+Example:
+
+  no_index:
+    file:
+    - My/Module.pm
+    directory:
+    - My/Private
+    package:
+    - My::Module::Stuff
+    namespace:
+    - My::Module::Stuff
+
+(Spec 1.1) [optional] {map} A YAML mapping that describes any files,
+directories, packages, and namespaces that are private
+(i.e. implementation artifacts) that are not of interest to searching
+and indexing tools.  This is useful when no C<provides> field is
+present.
+
+For example, L<http://search.cpan.org/> excludes items listed in C<no_index>
+when searching for POD, meaning files in these directories will not
+converted to HTML and made public - which is useful if you have
+example or test PODs that you don't want the search engine to go
+through.
+
+=head3 file
+
+(Spec 1.1) [optional] Exclude any listed file(s).
+
+=head3 directory
+
+(Spec 1.1) [optional] Exclude anything below the listed
+directory(ies).
+
+[Note: previous editions of the spec had C<dir> instead of
+C<directory>, but I think MakeMaker and various users started using
+C<directory>, so in deference we switched to that.]
+
+=head3 package
+
+(Spec 1.1) [optional] Exclude the listed package(s).
+
+=head3 namespace
+
+(Spec 1.1) [optional] Excludes anything below the listed namespace(s),
+but I<not> the listed namespace(s) its self.
+
+=head2 keywords
+
+Example:
+
+  keywords:
+    - make
+    - build
+    - install
+
+(Spec 1.1) [optional] {list} A sequence of keywords/phrases that describe
+this distribution.
+
+=head2 resources
+
+Example:
+
+  resources:
+    license: http://dev.perl.org/licenses/
+    homepage: http://sourceforge.net/projects/module-build
+    bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build
+    repository: http://sourceforge.net/cvs/?group_id=45731
+    MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general
+
+(Spec 1.1) [optional] {map} A mapping of any URL resources related to
+this distribution.  All-lower-case keys, such as C<homepage>,
+C<license>, and C<bugtracker>, are reserved by this specification, as
+they have "official" meanings defined here in this specification.  If
+you'd like to add your own "special" entries (like the "MailingList"
+entry above), use at least one upper-case letter.
+
+The current set of official keys is:
+
+=over 2
+
+=item homepage
+
+The official home of this project on the web.
+
+=item license
+
+An URL for an official statement of this distribution's license.
+
+=item bugtracker
+
+An URL for a bug tracker (e.g. Bugzilla or RT queue) for this project.
+
+=back
+
+
+=head2 generated_by
+
+Example:
+
+  generated_by: Module::Build version 0.20
+
+(Spec 1.0) [required] {string} Indicates the tool that was used to create this
+F<META.yml> file.  It's good form to include both the name of the tool
+and its version, but this field is essentially opaque, at least for
+the moment. If F<META.yml> was generated by hand, it is suggested that
+the author be specified here.
+
+[Note: My F<meta_stats.pl> script which I use to gather statistics
+regarding F<META.yml> usage prefers the form listed above, i.e. it
+splits on /\s+version\s+/ taking the first field as the name of the
+tool that generated the file and the second field as version of that
+tool. RWS]
+
+=head1 VERSION SPECIFICATIONS
+
+Some fields require a version specification (ex. L</requires>,
+L</recommends>, L</build_requires>, etc.) to indicate the particular
+versionZ<>(s) of some other module that may be required as a
+prerequisite.  This section details the version specification formats
+that are currently supported.
+
+The simplest format for a version specification is just the version
+number itself, e.g. C<2.4>.  This means that B<at least> version 2.4
+must be present.  To indicate that B<any> version of a prerequisite is
+okay, even if the prerequisite doesn't define a version at all, use
+the version C<0>.
+
+You may also use the operators E<lt> (less than), E<lt>= (less than or
+equal), E<gt> (greater than), E<gt>= (greater than or equal), ==
+(equal), and != (not equal).  For example, the specification C<E<lt>
+2.0> means that any version of the prerequisite less than 2.0 is
+suitable.
+
+For more complicated situations, version specifications may be AND-ed
+together using commas.  The specification C<E<gt>= 1.2, != 1.5, E<lt>
+2.0> indicates a version that must be B<at least> 1.2, B<less than>
+2.0, and B<not equal to> 1.5.
+
+=head1 SEE ALSO
+
+L<CPAN|http://www.cpan.org/>
+
+L<CPAN.pm|CPAN>
+
+L<CPANPLUS>
+
+L<Data::Dumper>
+
+L<ExtUtils::MakeMaker>
+
+L<Module::Build>
+
+L<Module::Install>
+
+L<XML|http://www.w3.org/XML/>
+
+L<YAML|http://www.yaml.org/>
+
+=head1 HISTORY
+
+=over 4
+
+=item March 14, 2003 (Pi day)
+
+=over 2
+
+=item *
+
+Created version 1.0 of this document.
+
+=back
+
+=item May 8, 2003
+
+=over 2
+
+=item *
+
+Added the L</dynamic_config> field, which was missing from the initial
+version.
+
+=back
+
+=item November 13, 2003
+
+=over 2
+
+=item *
+
+Added more YAML rationale articles.
+
+=item *
+
+Fixed existing link to YAML discussion thread to point to new
+L<http://nntp.x.perl.org/group/> site.
+
+=item *
+
+Added and deprecated the L</private> field.
+
+=item *
+
+Added L</abstract>, C<configure>, C<requires_packages>,
+C<requires_os>, C<excludes_os>, and L</no_index> fields.
+
+=item *
+
+Bumped version.
+
+=back
+
+=item November 16, 2003
+
+=over 2
+
+=item *
+
+Added C<generation>, C<authored_by> fields.
+
+=item *
+
+Add alternative proposal to the L</recommends> field.
+
+=item *
+
+Add proposal for a C<requires_build_tools> field.
+
+=back
+
+=item December 9, 2003
+
+=over 2
+
+=item *
+
+Added link to latest version of this specification on CPAN.
+
+=item *
+
+Added section L</"VERSION SPECIFICATIONS">.
+
+=item *
+
+Chang name from Module::Build::META-spec to CPAN::META::Specification.
+
+=item *
+
+Add proposal for C<auto_regenerate> field.
+
+=back
+
+=item December 15, 2003
+
+=over 2
+
+=item *
+
+Add C<index> field as a compliment to L</no_index>
+
+=item *
+
+Add L</keywords> field as a means to aid searching distributions.
+
+=item *
+
+Add L</TERMINOLOGY> section to explain certain terms that may be
+ambiguous.
+
+=back
+
+=item July 26, 2005
+
+=over 2
+
+=item *
+
+Removed a bunch of items (generation, requires_build_tools,
+requires_packages, configure, requires_os, excludes_os,
+auto_regenerate) that have never actually been supported, but were
+more like records of brainstorming.
+
+=item *
+
+Changed C<authored_by> to L</author>, since that's always been what
+it's actually called in actual F<META.yml> files.
+
+=item *
+
+Added the "==" operator to the list of supported version-checking
+operators.
+
+=item *
+
+Noted that the L</distribution_type> field is basically meaningless,
+and shouldn't really be used.
+
+=item *
+
+Clarified L</dynamic_config> a bit.
+
+=back
+
+=item August 23, 2005
+
+=over 2
+
+=item *
+
+Removed the name C<CPAN::META::Specification>, since that implies a
+module that doesn't actually exist.
+
+=back
+
+=back

database/perl/lib/CPAN/Meta/History/Meta_1_4.pod

@@ -0,0 +1,765 @@
+=for :stopwords MailingList PODs RWS subcontext
+
+=head1 NAME
+
+CPAN::Meta::History::Meta_1_4 - Version 1.4 metadata specification for META.yml
+
+=head1 PREFACE
+
+This is a historical copy of the version 1.4 specification for F<META.yml>
+files, copyright by Ken Williams and licensed under the same terms as Perl
+itself.
+
+Modifications from the original:
+
+=over
+
+=item *
+
+Various spelling corrections
+
+=item *
+
+Include list of valid licenses from L<Module::Build> 0.2807 rather than
+linking to the module, with minor updates to text and links to reflect
+versions at the time of publication.
+
+=item *
+
+Fixed some dead links to point to active resources.
+
+=back
+
+=head1 SYNOPSIS
+
+ --- #YAML:1.0
+ name: Module-Build
+ abstract: Build and install Perl modules
+ version: 0.20
+ author:
+   - Ken Williams <kwilliams@cpan.org>
+ license: perl
+ distribution_type: module
+ requires:
+   Config: 0
+   Cwd: 0
+   Data::Dumper: 0
+   ExtUtils::Install: 0
+   File::Basename: 0
+   File::Compare: 0
+   File::Copy: 0
+   File::Find: 0
+   File::Path: 0
+   File::Spec: 0
+   IO::File: 0
+   perl: 5.005_03
+ recommends:
+   Archive::Tar: 1.00
+   ExtUtils::Install: 0.3
+   ExtUtils::ParseXS: 2.02
+   Pod::Text: 0
+   YAML: 0.35
+ build_requires:
+   Test: 0
+ resources:
+   license: http://dev.perl.org/licenses/
+ meta-spec:
+   version: 1.4
+   url: http://module-build.sourceforge.net/META-spec-v1.3.html
+ generated_by: Module::Build version 0.20
+
+=head1 DESCRIPTION
+
+This document describes version 1.4 of the F<META.yml> specification.
+
+The F<META.yml> file describes important properties of contributed
+Perl distributions such as the ones found on CPAN.  It is typically
+created by tools like Module::Build, Module::Install, and
+ExtUtils::MakeMaker.
+
+The fields in the F<META.yml> file are meant to be helpful for people
+maintaining module collections (like CPAN), for people writing
+installation tools (like CPAN.pm or CPANPLUS), or just for people who
+want to know some stuff about a distribution before downloading it and
+starting to install it.
+
+I<Note: The latest stable version of this specification can always be
+found at L<http://module-build.sourceforge.net/META-spec-current.html>,
+and the latest development version (which may include things that
+won't make it into the stable version) can always be found at
+L<http://module-build.sourceforge.net/META-spec-blead.html>.>
+
+=head1 FORMAT
+
+F<META.yml> files are written in the YAML format (see
+L<http://www.yaml.org/>).
+
+See the following links to learn why we chose YAML instead of, say,
+XML or Data::Dumper:
+
+=over 4
+
+=item *
+
+L<Module::Build design plans|http://www.nntp.perl.org/group/perl.makemaker/2002/04/msg407.html>
+
+=item *
+
+L<Not keen on YAML|http://www.nntp.perl.org/group/perl.module-authors/2003/11/msg1353.html>
+
+=item *
+
+L<META Concerns|http://www.nntp.perl.org/group/perl.module-authors/2003/11/msg1385.html>
+
+=back
+
+=head1 TERMINOLOGY
+
+=over 4
+
+=item distribution
+
+This is the primary object described by the F<META.yml>
+specification. In the context of this document it usually refers to a
+collection of modules, scripts, and/or documents that are distributed
+together for other developers to use.  Examples of distributions are
+C<Class-Container>, C<libwww-perl>, or C<DBI>.
+
+=item module
+
+This refers to a reusable library of code typically contained in a
+single file. Currently, we primarily talk of perl modules, but this
+specification should be open enough to apply to other languages as
+well (ex. python, ruby).  Examples of modules are C<Class::Container>,
+C<LWP::Simple>, or C<DBD::File>.
+
+=back
+
+=head1 HEADER
+
+The first line of a F<META.yml> file should be a valid YAML document
+header like C<"--- #YAML:1.0">.
+
+=head1 FIELDS
+
+The rest of the F<META.yml> file is one big YAML mapping whose keys
+are described here.
+
+=head2 meta-spec
+
+Example:
+
+ meta-spec:
+   version: 1.4
+   url: http://module-build.sourceforge.net/META-spec-v1.3.html
+
+(Spec 1.1) [required] {URL} This field indicates the location of the
+version of the META.yml specification used.
+
+=head2 name
+
+Example:
+
+  name: Module-Build
+
+(Spec 1.0) [required] {string} The name of the distribution which is often
+created by taking the "main module" in the distribution and changing
+"::" to "-".  Sometimes it's completely different, however, as in the
+case of the libwww-perl distribution (see
+L<http://search.cpan.org/dist/libwww-perl/>).
+
+=head2 version
+
+Example:
+
+  version: 0.20
+
+(Spec 1.0) [required] {version} The version of the distribution to which the
+F<META.yml> file refers.
+
+=head2 abstract
+
+Example:
+
+  abstract: Build and install Perl modules.
+
+(Spec 1.1) [required] {string} A short description of the purpose of the
+distribution.
+
+=head2 author
+
+Example:
+
+  author:
+    - Ken Williams <kwilliams@cpan.org>
+
+(Spec 1.1) [required] {list of strings} A YAML sequence indicating the author(s) of the
+distribution. The preferred form is author-name <email-address>.
+
+=head2 license
+
+Example:
+
+  license: perl
+
+(Spec 1.0) [required] {string} The license under which this
+distribution may be used and redistributed.
+
+Must be one of the following licenses:
+
+=over 4
+
+=item apache
+
+The distribution is licensed under the Apache Software License version 1.1
+(L<http://opensource.org/licenses/Apache-1.1>).
+
+=item artistic
+
+The distribution is licensed under the Artistic License version 1, as specified
+by the Artistic file in the standard perl distribution
+(L<http://opensource.org/licenses/Artistic-Perl-1.0>).
+
+=item bsd
+
+The distribution is licensed under the BSD 3-Clause License
+(L<http://opensource.org/licenses/BSD-3-Clause>).
+
+=item gpl
+
+The distribution is distributed under the terms of the GNU General Public
+License version 2 (L<http://opensource.org/licenses/GPL-2.0>).
+
+=item lgpl
+
+The distribution is distributed under the terms of the GNU Lesser General
+Public License version 2 (L<http://opensource.org/licenses/LGPL-2.1>).
+
+=item mit
+
+The distribution is licensed under the MIT License
+(L<http://opensource.org/licenses/MIT>).
+
+=item mozilla
+
+The distribution is licensed under the Mozilla Public License.
+(L<http://opensource.org/licenses/MPL-1.0> or
+L<http://opensource.org/licenses/MPL-1.1>)
+
+=item open_source
+
+The distribution is licensed under some other Open Source Initiative-approved
+license listed at L<http://www.opensource.org/licenses/>.
+
+=item perl
+
+The distribution may be copied and redistributed under the same terms as perl
+itself (this is by far the most common licensing option for modules on CPAN).
+This is a dual license, in which the user may choose between either the GPL or
+the Artistic license.
+
+=item restrictive
+
+The distribution may not be redistributed without special permission from the
+author and/or copyright holder.
+
+=item unrestricted
+
+The distribution is licensed under a license that is not approved by
+L<www.opensource.org|http://www.opensource.org/> but that allows distribution
+without restrictions.
+
+=back
+
+=head2 distribution_type
+
+Example:
+
+  distribution_type: module
+
+(Spec 1.0) [optional] {string} What kind of stuff is contained in this
+distribution.  Most things on CPAN are C<module>s (which can also mean
+a collection of modules), but some things are C<script>s.
+
+Unfortunately this field is basically meaningless, since many
+distributions are hybrids of several kinds of things, or some new
+thing, or subjectively different in focus depending on who's using
+them.  Tools like Module::Build and MakeMaker will likely stop
+generating this field.
+
+=head2 requires
+
+Example:
+
+  requires:
+    Data::Dumper: 0
+    File::Find: 1.03
+
+(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl
+prerequisites this distribution requires for proper operation.  The
+keys are the names of the prerequisites (module names or 'perl'), and
+the values are version specifications as described in L<VERSION
+SPECIFICATIONS>.
+
+=head2 recommends
+
+Example:
+
+  recommends:
+    Data::Dumper: 0
+    File::Find: 1.03
+
+(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl
+prerequisites this distribution recommends for enhanced operation.
+The keys are the names of the prerequisites (module names or 'perl'),
+and the values are version specifications as described in L<VERSION
+SPECIFICATIONS>.
+
+
+
+I<ALTERNATIVE: It may be desirable to present to the user which
+features depend on which modules so they can make an informed decision
+about which recommended modules to install.>
+
+Example:
+
+  optional_features:
+    foo:
+      description: Provides the ability to blah.
+      requires:
+        Data::Dumper: 0
+        File::Find: 1.03
+
+I<(Spec 1.1) [optional] {map} A YAML mapping of names for optional features
+which are made available when its requirements are met. For each
+feature a description is provided along with any of L</requires>,
+L</build_requires>, and L</conflicts>, which have the same meaning in
+this subcontext as described elsewhere in this document.>
+
+=head2 build_requires
+
+Example:
+
+  build_requires:
+    Data::Dumper: 0
+    File::Find: 1.03
+
+(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl
+prerequisites required for building and/or testing of this
+distribution.  The keys are the names of the prerequisites (module
+names or 'perl'), and the values are version specifications as
+described in L</"VERSION SPECIFICATIONS">.  These dependencies are not
+required after the distribution is installed.
+
+=head2 configure_requires
+
+Example:
+
+  configure_requires:
+    Module::Build: 0.2809
+    Data::Dumper: 0
+    File::Find: 1.03
+
+(Spec 1.4) [optional] {map} A YAML mapping indicating the Perl prerequisites
+required before configuring this distribution.  The keys are the
+names of the prerequisites (module names or 'perl'), and the values are version
+specifications as described in L</"VERSION SPECIFICATIONS">.  These
+dependencies are not required after the distribution is installed.
+
+=head2 conflicts
+
+Example:
+
+  conflicts:
+    Data::Dumper: 0
+    File::Find: 1.03
+
+(Spec 1.0) [optional] {map} A YAML mapping indicating any items that
+cannot be installed while this distribution is installed.  This is a
+pretty uncommon situation.  The keys for C<conflicts> are the item
+names (module names or 'perl'), and the values are version
+specifications as described in L</"VERSION SPECIFICATIONS">.
+
+
+=head2 dynamic_config
+
+Example:
+
+  dynamic_config: 0
+
+(Spec 1.0) [optional] {boolean} A boolean flag indicating whether a F<Build.PL>
+or F<Makefile.PL> (or similar) must be executed when building this
+distribution, or whether it can be built, tested and installed solely
+from consulting its
+metadata file.  The main reason to set this to a true value is that
+your module performs some dynamic configuration (asking questions,
+sensing the environment, etc.) as part of its build/install process.
+
+Currently Module::Build doesn't actually do anything with this flag
+- it's probably going to be up to higher-level tools like CPAN
+to do something useful with it.  It can potentially bring lots of
+security, packaging, and convenience improvements.
+
+If this field is omitted, it defaults to 1 (true).
+
+=head2 private
+
+I<(Deprecated)> (Spec 1.0) [optional] {map} This field has been renamed to
+L</no_index>.  See below.
+
+=head2 provides
+
+Example:
+
+  provides:
+    Foo::Bar:
+      file: lib/Foo/Bar.pm
+      version: 0.27_02
+    Foo::Bar::Blah:
+      file: lib/Foo/Bar/Blah.pm
+    Foo::Bar::Baz:
+      file: lib/Foo/Bar/Baz.pm
+      version: 0.3
+
+(Spec 1.1) [optional] {map} A YAML mapping that describes all packages
+provided by this distribution.  This information can be (and, in some
+cases, is) used by distribution and automation mechanisms like PAUSE,
+CPAN, and search.cpan.org to build indexes saying in which
+distribution various packages can be found.
+
+When using tools like L<Module::Build> that can generate the
+C<provides> mapping for your distribution automatically, make sure you
+examine what it generates to make sure it makes sense - indexers will
+usually trust the C<provides> field if it's present, rather than
+scanning through the distribution files themselves to figure out
+packages and versions.  This is a good thing, because it means you can
+use the C<provides> field to tell the indexers precisely what you want
+indexed about your distribution, rather than relying on them to
+essentially guess what you want indexed.
+
+=head2 no_index
+
+Example:
+
+  no_index:
+    file:
+    - My/Module.pm
+    directory:
+    - My/Private
+    package:
+    - My::Module::Stuff
+    namespace:
+    - My::Module::Stuff
+
+(Spec 1.1) [optional] {map} A YAML mapping that describes any files,
+directories, packages, and namespaces that are private
+(i.e. implementation artifacts) that are not of interest to searching
+and indexing tools.  This is useful when no C<provides> field is
+present.
+
+For example, L<http://search.cpan.org/> excludes items listed in C<no_index>
+when searching for POD, meaning files in these directories will not
+converted to HTML and made public - which is useful if you have
+example or test PODs that you don't want the search engine to go
+through.
+
+=head3 file
+
+(Spec 1.1) [optional] Exclude any listed file(s).
+
+=head3 directory
+
+(Spec 1.1) [optional] Exclude anything below the listed
+directory(ies).
+
+[Note: previous editions of the spec had C<dir> instead of
+C<directory>, but I think MakeMaker and various users started using
+C<directory>, so in deference we switched to that.]
+
+=head3 package
+
+(Spec 1.1) [optional] Exclude the listed package(s).
+
+=head3 namespace
+
+(Spec 1.1) [optional] Excludes anything below the listed namespace(s),
+but I<not> the listed namespace(s) its self.
+
+=head2 keywords
+
+Example:
+
+  keywords:
+    - make
+    - build
+    - install
+
+(Spec 1.1) [optional] {list} A sequence of keywords/phrases that describe
+this distribution.
+
+=head2 resources
+
+Example:
+
+  resources:
+    license: http://dev.perl.org/licenses/
+    homepage: http://sourceforge.net/projects/module-build
+    bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build
+    repository: http://sourceforge.net/cvs/?group_id=45731
+    MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general
+
+(Spec 1.1) [optional] {map} A mapping of any URL resources related to
+this distribution.  All-lower-case keys, such as C<homepage>,
+C<license>, and C<bugtracker>, are reserved by this specification, as
+they have "official" meanings defined here in this specification.  If
+you'd like to add your own "special" entries (like the "MailingList"
+entry above), use at least one upper-case letter.
+
+The current set of official keys is:
+
+=over 2
+
+=item homepage
+
+The official home of this project on the web.
+
+=item license
+
+An URL for an official statement of this distribution's license.
+
+=item bugtracker
+
+An URL for a bug tracker (e.g. Bugzilla or RT queue) for this project.
+
+=back
+
+
+=head2 generated_by
+
+Example:
+
+  generated_by: Module::Build version 0.20
+
+(Spec 1.0) [required] {string} Indicates the tool that was used to create this
+F<META.yml> file.  It's good form to include both the name of the tool
+and its version, but this field is essentially opaque, at least for
+the moment. If F<META.yml> was generated by hand, it is suggested that
+the author be specified here.
+
+[Note: My F<meta_stats.pl> script which I use to gather statistics
+regarding F<META.yml> usage prefers the form listed above, i.e. it
+splits on /\s+version\s+/ taking the first field as the name of the
+tool that generated the file and the second field as version of that
+tool. RWS]
+
+=head1 VERSION SPECIFICATIONS
+
+Some fields require a version specification (ex. L</requires>,
+L</recommends>, L</build_requires>, etc.) to indicate the particular
+versionZ<>(s) of some other module that may be required as a
+prerequisite.  This section details the version specification formats
+that are currently supported.
+
+The simplest format for a version specification is just the version
+number itself, e.g. C<2.4>.  This means that B<at least> version 2.4
+must be present.  To indicate that B<any> version of a prerequisite is
+okay, even if the prerequisite doesn't define a version at all, use
+the version C<0>.
+
+You may also use the operators E<lt> (less than), E<lt>= (less than or
+equal), E<gt> (greater than), E<gt>= (greater than or equal), ==
+(equal), and != (not equal).  For example, the specification C<E<lt>
+2.0> means that any version of the prerequisite less than 2.0 is
+suitable.
+
+For more complicated situations, version specifications may be AND-ed
+together using commas.  The specification C<E<gt>= 1.2, != 1.5, E<lt>
+2.0> indicates a version that must be B<at least> 1.2, B<less than>
+2.0, and B<not equal to> 1.5.
+
+=head1 SEE ALSO
+
+L<CPAN|http://www.cpan.org/>
+
+L<CPAN.pm|CPAN>
+
+L<CPANPLUS>
+
+L<Data::Dumper>
+
+L<ExtUtils::MakeMaker>
+
+L<Module::Build>
+
+L<Module::Install>
+
+L<XML|http://www.w3.org/XML/>
+
+L<YAML|http://www.yaml.org/>
+
+=head1 HISTORY
+
+=over 4
+
+=item March 14, 2003 (Pi day)
+
+=over 2
+
+=item *
+
+Created version 1.0 of this document.
+
+=back
+
+=item May 8, 2003
+
+=over 2
+
+=item *
+
+Added the L</dynamic_config> field, which was missing from the initial
+version.
+
+=back
+
+=item November 13, 2003
+
+=over 2
+
+=item *
+
+Added more YAML rationale articles.
+
+=item *
+
+Fixed existing link to YAML discussion thread to point to new
+L<http://nntp.x.perl.org/group/> site.
+
+=item *
+
+Added and deprecated the L</private> field.
+
+=item *
+
+Added L</abstract>, C<configure>, C<requires_packages>,
+C<requires_os>, C<excludes_os>, and L</no_index> fields.
+
+=item *
+
+Bumped version.
+
+=back
+
+=item November 16, 2003
+
+=over 2
+
+=item *
+
+Added C<generation>, C<authored_by> fields.
+
+=item *
+
+Add alternative proposal to the L</recommends> field.
+
+=item *
+
+Add proposal for a C<requires_build_tools> field.
+
+=back
+
+=item December 9, 2003
+
+=over 2
+
+=item *
+
+Added link to latest version of this specification on CPAN.
+
+=item *
+
+Added section L</"VERSION SPECIFICATIONS">.
+
+=item *
+
+Chang name from Module::Build::META-spec to CPAN::META::Specification.
+
+=item *
+
+Add proposal for C<auto_regenerate> field.
+
+=back
+
+=item December 15, 2003
+
+=over 2
+
+=item *
+
+Add C<index> field as a compliment to L</no_index>
+
+=item *
+
+Add L</keywords> field as a means to aid searching distributions.
+
+=item *
+
+Add L</TERMINOLOGY> section to explain certain terms that may be
+ambiguous.
+
+=back
+
+=item July 26, 2005
+
+=over 2
+
+=item *
+
+Removed a bunch of items (generation, requires_build_tools,
+requires_packages, configure, requires_os, excludes_os,
+auto_regenerate) that have never actually been supported, but were
+more like records of brainstorming.
+
+=item *
+
+Changed C<authored_by> to L</author>, since that's always been what
+it's actually called in actual F<META.yml> files.
+
+=item *
+
+Added the "==" operator to the list of supported version-checking
+operators.
+
+=item *
+
+Noted that the L</distribution_type> field is basically meaningless,
+and shouldn't really be used.
+
+=item *
+
+Clarified L</dynamic_config> a bit.
+
+=back
+
+=item August 23, 2005
+
+=over 2
+
+=item *
+
+Removed the name C<CPAN::META::Specification>, since that implies a
+module that doesn't actually exist.
+
+=back
+
+=item June 12, 2007
+
+=over 2
+
+=item *
+
+Added L</configure_requires>.
+
+=back
+
+=back

database/perl/lib/CPAN/Meta/Merge.pm

@@ -0,0 +1,351 @@
+use strict;
+use warnings;
+
+package CPAN::Meta::Merge;
+
+our $VERSION = '2.150010';
+
+use Carp qw/croak/;
+use Scalar::Util qw/blessed/;
+use CPAN::Meta::Converter 2.141170;
+
+sub _is_identical {
+  my ($left, $right) = @_;
+  return
+    (not defined $left and not defined $right)
+    # if either of these are references, we compare the serialized value
+    || (defined $left and defined $right and $left eq $right);
+}
+
+sub _identical {
+  my ($left, $right, $path) = @_;
+  croak sprintf "Can't merge attribute %s: '%s' does not equal '%s'", join('.', @{$path}), $left, $right
+    unless _is_identical($left, $right);
+  return $left;
+}
+
+sub _merge {
+  my ($current, $next, $mergers, $path) = @_;
+  for my $key (keys %{$next}) {
+    if (not exists $current->{$key}) {
+      $current->{$key} = $next->{$key};
+    }
+    elsif (my $merger = $mergers->{$key}) {
+      $current->{$key} = $merger->($current->{$key}, $next->{$key}, [ @{$path}, $key ]);
+    }
+    elsif ($merger = $mergers->{':default'}) {
+      $current->{$key} = $merger->($current->{$key}, $next->{$key}, [ @{$path}, $key ]);
+    }
+    else {
+      croak sprintf "Can't merge unknown attribute '%s'", join '.', @{$path}, $key;
+    }
+  }
+  return $current;
+}
+
+sub _uniq {
+  my %seen = ();
+  return grep { not $seen{$_}++ } @_;
+}
+
+sub _set_addition {
+  my ($left, $right) = @_;
+  return [ +_uniq(@{$left}, @{$right}) ];
+}
+
+sub _uniq_map {
+  my ($left, $right, $path) = @_;
+  for my $key (keys %{$right}) {
+    if (not exists $left->{$key}) {
+      $left->{$key} = $right->{$key};
+    }
+    # identical strings or references are merged identically
+    elsif (_is_identical($left->{$key}, $right->{$key})) {
+      1; # do nothing - keep left
+    }
+    elsif (ref $left->{$key} eq 'HASH' and ref $right->{$key} eq 'HASH') {
+      $left->{$key} = _uniq_map($left->{$key}, $right->{$key}, [ @{$path}, $key ]);
+    }
+    else {
+      croak 'Duplication of element ' . join '.', @{$path}, $key;
+    }
+  }
+  return $left;
+}
+
+sub _improvise {
+  my ($left, $right, $path) = @_;
+  my ($name) = reverse @{$path};
+  if ($name =~ /^x_/) {
+    if (ref($left) eq 'ARRAY') {
+      return _set_addition($left, $right, $path);
+    }
+    elsif (ref($left) eq 'HASH') {
+      return _uniq_map($left, $right, $path);
+    }
+    else {
+      return _identical($left, $right, $path);
+    }
+  }
+  croak sprintf "Can't merge '%s'", join '.', @{$path};
+}
+
+sub _optional_features {
+  my ($left, $right, $path) = @_;
+
+  for my $key (keys %{$right}) {
+    if (not exists $left->{$key}) {
+      $left->{$key} = $right->{$key};
+    }
+    else {
+      for my $subkey (keys %{ $right->{$key} }) {
+        next if $subkey eq 'prereqs';
+        if (not exists $left->{$key}{$subkey}) {
+          $left->{$key}{$subkey} = $right->{$key}{$subkey};
+        }
+        else {
+          Carp::croak "Cannot merge two optional_features named '$key' with different '$subkey' values"
+            if do { no warnings 'uninitialized'; $left->{$key}{$subkey} ne $right->{$key}{$subkey} };
+        }
+      }
+
+      require CPAN::Meta::Prereqs;
+      $left->{$key}{prereqs} =
+        CPAN::Meta::Prereqs->new($left->{$key}{prereqs})
+          ->with_merged_prereqs(CPAN::Meta::Prereqs->new($right->{$key}{prereqs}))
+          ->as_string_hash;
+    }
+  }
+  return $left;
+}
+
+
+my %default = (
+  abstract       => \&_identical,
+  author         => \&_set_addition,
+  dynamic_config => sub {
+    my ($left, $right) = @_;
+    return $left || $right;
+  },
+  generated_by => sub {
+    my ($left, $right) = @_;
+    return join ', ', _uniq(split(/, /, $left), split(/, /, $right));
+  },
+  license     => \&_set_addition,
+  'meta-spec' => {
+    version => \&_identical,
+    url     => \&_identical
+  },
+  name              => \&_identical,
+  release_status    => \&_identical,
+  version           => \&_identical,
+  description       => \&_identical,
+  keywords          => \&_set_addition,
+  no_index          => { map { ($_ => \&_set_addition) } qw/file directory package namespace/ },
+  optional_features => \&_optional_features,
+  prereqs           => sub {
+    require CPAN::Meta::Prereqs;
+    my ($left, $right) = map { CPAN::Meta::Prereqs->new($_) } @_[0,1];
+    return $left->with_merged_prereqs($right)->as_string_hash;
+  },
+  provides  => \&_uniq_map,
+  resources => {
+    license    => \&_set_addition,
+    homepage   => \&_identical,
+    bugtracker => \&_uniq_map,
+    repository => \&_uniq_map,
+    ':default' => \&_improvise,
+  },
+  ':default' => \&_improvise,
+);
+
+sub new {
+  my ($class, %arguments) = @_;
+  croak 'default version required' if not exists $arguments{default_version};
+  my %mapping = %default;
+  my %extra = %{ $arguments{extra_mappings} || {} };
+  for my $key (keys %extra) {
+    if (ref($mapping{$key}) eq 'HASH') {
+      $mapping{$key} = { %{ $mapping{$key} }, %{ $extra{$key} } };
+    }
+    else {
+      $mapping{$key} = $extra{$key};
+    }
+  }
+  return bless {
+    default_version => $arguments{default_version},
+    mapping => _coerce_mapping(\%mapping, []),
+  }, $class;
+}
+
+my %coderef_for = (
+  set_addition => \&_set_addition,
+  uniq_map     => \&_uniq_map,
+  identical    => \&_identical,
+  improvise    => \&_improvise,
+  improvize    => \&_improvise, # [sic] for backwards compatibility
+);
+
+sub _coerce_mapping {
+  my ($orig, $map_path) = @_;
+  my %ret;
+  for my $key (keys %{$orig}) {
+    my $value = $orig->{$key};
+    if (ref($orig->{$key}) eq 'CODE') {
+      $ret{$key} = $value;
+    }
+    elsif (ref($value) eq 'HASH') {
+      my $mapping = _coerce_mapping($value, [ @{$map_path}, $key ]);
+      $ret{$key} = sub {
+        my ($left, $right, $path) = @_;
+        return _merge($left, $right, $mapping, [ @{$path} ]);
+      };
+    }
+    elsif ($coderef_for{$value}) {
+      $ret{$key} = $coderef_for{$value};
+    }
+    else {
+      croak "Don't know what to do with " . join '.', @{$map_path}, $key;
+    }
+  }
+  return \%ret;
+}
+
+sub merge {
+  my ($self, @items) = @_;
+  my $current = {};
+  for my $next (@items) {
+    if ( blessed($next) && $next->isa('CPAN::Meta') ) {
+      $next = $next->as_struct;
+    }
+    elsif ( ref($next) eq 'HASH' ) {
+      my $cmc = CPAN::Meta::Converter->new(
+        $next, default_version => $self->{default_version}
+      );
+      $next = $cmc->upgrade_fragment;
+    }
+    else {
+      croak "Don't know how to merge '$next'";
+    }
+    $current = _merge($current, $next, $self->{mapping}, []);
+  }
+  return $current;
+}
+
+1;
+
+# ABSTRACT: Merging CPAN Meta fragments
+
+
+# vim: ts=2 sts=2 sw=2 et :
+
+__END__
+
+=pod
+
+=encoding UTF-8
+
+=head1 NAME
+
+CPAN::Meta::Merge - Merging CPAN Meta fragments
+
+=head1 VERSION
+
+version 2.150010
+
+=head1 SYNOPSIS
+
+ my $merger = CPAN::Meta::Merge->new(default_version => "2");
+ my $meta = $merger->merge($base, @additional);
+
+=head1 DESCRIPTION
+
+=head1 METHODS
+
+=head2 new
+
+This creates a CPAN::Meta::Merge object. It takes one mandatory named
+argument, C<version>, declaring the version of the meta-spec that must be
+used for the merge. It can optionally take an C<extra_mappings> argument
+that allows one to add additional merging functions for specific elements.
+
+The C<extra_mappings> arguments takes a hash ref with the same type of
+structure as described in L<CPAN::Meta::Spec>, except with its values as
+one of the L<defined merge strategies|/"MERGE STRATEGIES"> or a code ref
+to a merging function.
+
+  my $merger = CPAN::Meta::Merge->new(
+      default_version => '2',
+      extra_mappings => {
+          'optional_features' => \&custom_merge_function,
+          'x_custom' => 'set_addition',
+          'x_meta_meta' => {
+              name => 'identical',
+              tags => 'set_addition',
+          }
+      }
+  );
+
+=head2 merge(@fragments)
+
+Merge all C<@fragments> together. It will accept both CPAN::Meta objects and
+(possibly incomplete) hashrefs of metadata.
+
+=head1 MERGE STRATEGIES
+
+C<merge> uses various strategies to combine different elements of the CPAN::Meta objects.  The following strategies can be used with the extra_mappings argument of C<new>:
+
+=over
+
+=item identical
+
+The elements must be identical
+
+=item set_addition
+
+The union of two array refs
+
+  [ a, b ] U [ a, c]  = [ a, b, c ]
+
+=item uniq_map
+
+Key value pairs from the right hash are merged to the left hash.  Key
+collisions are only allowed if their values are the same.  This merge
+function will recurse into nested hash refs following the same merge
+rules.
+
+=item improvise
+
+This merge strategy will try to pick the appropriate predefined strategy
+based on what element type.  Array refs will try to use the
+C<set_addition> strategy,  Hash refs will try to use the C<uniq_map>
+strategy, and everything else will try the C<identical> strategy.
+
+=back
+
+=head1 AUTHORS
+
+=over 4
+
+=item *
+
+David Golden <dagolden@cpan.org>
+
+=item *
+
+Ricardo Signes <rjbs@cpan.org>
+
+=item *
+
+Adam Kennedy <adamk@cpan.org>
+
+=back
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2010 by David Golden, Ricardo Signes, Adam Kennedy and Contributors.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut

database/perl/lib/CPAN/Meta/Prereqs.pm

@@ -0,0 +1,481 @@
+use 5.006;
+use strict;
+use warnings;
+package CPAN::Meta::Prereqs;
+
+our $VERSION = '2.150010';
+
+#pod =head1 DESCRIPTION
+#pod
+#pod A CPAN::Meta::Prereqs object represents the prerequisites for a CPAN
+#pod distribution or one of its optional features.  Each set of prereqs is
+#pod organized by phase and type, as described in L<CPAN::Meta::Prereqs>.
+#pod
+#pod =cut
+
+use Carp qw(confess);
+use Scalar::Util qw(blessed);
+use CPAN::Meta::Requirements 2.121;
+
+#pod =method new
+#pod
+#pod   my $prereq = CPAN::Meta::Prereqs->new( \%prereq_spec );
+#pod
+#pod This method returns a new set of Prereqs.  The input should look like the
+#pod contents of the C<prereqs> field described in L<CPAN::Meta::Spec>, meaning
+#pod something more or less like this:
+#pod
+#pod   my $prereq = CPAN::Meta::Prereqs->new({
+#pod     runtime => {
+#pod       requires => {
+#pod         'Some::Module' => '1.234',
+#pod         ...,
+#pod       },
+#pod       ...,
+#pod     },
+#pod     ...,
+#pod   });
+#pod
+#pod You can also construct an empty set of prereqs with:
+#pod
+#pod   my $prereqs = CPAN::Meta::Prereqs->new;
+#pod
+#pod This empty set of prereqs is useful for accumulating new prereqs before finally
+#pod dumping the whole set into a structure or string.
+#pod
+#pod =cut
+
+# note we also accept anything matching /\Ax_/i
+sub __legal_phases { qw(configure build test runtime develop)   }
+sub __legal_types  { qw(requires recommends suggests conflicts) }
+
+# expect a prereq spec from META.json -- rjbs, 2010-04-11
+sub new {
+  my ($class, $prereq_spec) = @_;
+  $prereq_spec ||= {};
+
+  my %is_legal_phase = map {; $_ => 1 } $class->__legal_phases;
+  my %is_legal_type  = map {; $_ => 1 } $class->__legal_types;
+
+  my %guts;
+  PHASE: for my $phase (keys %$prereq_spec) {
+    next PHASE unless $phase =~ /\Ax_/i or $is_legal_phase{$phase};
+
+    my $phase_spec = $prereq_spec->{ $phase };
+    next PHASE unless keys %$phase_spec;
+
+    TYPE: for my $type (keys %$phase_spec) {
+      next TYPE unless $type =~ /\Ax_/i or $is_legal_type{$type};
+
+      my $spec = $phase_spec->{ $type };
+
+      next TYPE unless keys %$spec;
+
+      $guts{prereqs}{$phase}{$type} = CPAN::Meta::Requirements->from_string_hash(
+        $spec
+      );
+    }
+  }
+
+  return bless \%guts => $class;
+}
+
+#pod =method requirements_for
+#pod
+#pod   my $requirements = $prereqs->requirements_for( $phase, $type );
+#pod
+#pod This method returns a L<CPAN::Meta::Requirements> object for the given
+#pod phase/type combination.  If no prerequisites are registered for that
+#pod combination, a new CPAN::Meta::Requirements object will be returned, and it may
+#pod be added to as needed.
+#pod
+#pod If C<$phase> or C<$type> are undefined or otherwise invalid, an exception will
+#pod be raised.
+#pod
+#pod =cut
+
+sub requirements_for {
+  my ($self, $phase, $type) = @_;
+
+  confess "requirements_for called without phase" unless defined $phase;
+  confess "requirements_for called without type"  unless defined $type;
+
+  unless ($phase =~ /\Ax_/i or grep { $phase eq $_ } $self->__legal_phases) {
+    confess "requested requirements for unknown phase: $phase";
+  }
+
+  unless ($type =~ /\Ax_/i or grep { $type eq $_ } $self->__legal_types) {
+    confess "requested requirements for unknown type: $type";
+  }
+
+  my $req = ($self->{prereqs}{$phase}{$type} ||= CPAN::Meta::Requirements->new);
+
+  $req->finalize if $self->is_finalized;
+
+  return $req;
+}
+
+#pod =method phases
+#pod
+#pod   my @phases = $prereqs->phases;
+#pod
+#pod This method returns the list of all phases currently populated in the prereqs
+#pod object, suitable for iterating.
+#pod
+#pod =cut
+
+sub phases {
+  my ($self) = @_;
+
+  my %is_legal_phase = map {; $_ => 1 } $self->__legal_phases;
+  grep { /\Ax_/i or $is_legal_phase{$_} } keys %{ $self->{prereqs} };
+}
+
+#pod =method types_in
+#pod
+#pod   my @runtime_types = $prereqs->types_in('runtime');
+#pod
+#pod This method returns the list of all types currently populated in the prereqs
+#pod object for the provided phase, suitable for iterating.
+#pod
+#pod =cut
+
+sub types_in {
+  my ($self, $phase) = @_;
+
+  return unless $phase =~ /\Ax_/i or grep { $phase eq $_ } $self->__legal_phases;
+
+  my %is_legal_type  = map {; $_ => 1 } $self->__legal_types;
+  grep { /\Ax_/i or $is_legal_type{$_} } keys %{ $self->{prereqs}{$phase} };
+}
+
+#pod =method with_merged_prereqs
+#pod
+#pod   my $new_prereqs = $prereqs->with_merged_prereqs( $other_prereqs );
+#pod
+#pod   my $new_prereqs = $prereqs->with_merged_prereqs( \@other_prereqs );
+#pod
+#pod This method returns a new CPAN::Meta::Prereqs objects in which all the
+#pod other prerequisites given are merged into the current set.  This is primarily
+#pod provided for combining a distribution's core prereqs with the prereqs of one of
+#pod its optional features.
+#pod
+#pod The new prereqs object has no ties to the originals, and altering it further
+#pod will not alter them.
+#pod
+#pod =cut
+
+sub with_merged_prereqs {
+  my ($self, $other) = @_;
+
+  my @other = blessed($other) ? $other : @$other;
+
+  my @prereq_objs = ($self, @other);
+
+  my %new_arg;
+
+  for my $phase (__uniq(map { $_->phases } @prereq_objs)) {
+    for my $type (__uniq(map { $_->types_in($phase) } @prereq_objs)) {
+
+      my $req = CPAN::Meta::Requirements->new;
+
+      for my $prereq (@prereq_objs) {
+        my $this_req = $prereq->requirements_for($phase, $type);
+        next unless $this_req->required_modules;
+
+        $req->add_requirements($this_req);
+      }
+
+      next unless $req->required_modules;
+
+      $new_arg{ $phase }{ $type } = $req->as_string_hash;
+    }
+  }
+
+  return (ref $self)->new(\%new_arg);
+}
+
+#pod =method merged_requirements
+#pod
+#pod     my $new_reqs = $prereqs->merged_requirements( \@phases, \@types );
+#pod     my $new_reqs = $prereqs->merged_requirements( \@phases );
+#pod     my $new_reqs = $prereqs->merged_requirements();
+#pod
+#pod This method joins together all requirements across a number of phases
+#pod and types into a new L<CPAN::Meta::Requirements> object.  If arguments
+#pod are omitted, it defaults to "runtime", "build" and "test" for phases
+#pod and "requires" and "recommends" for types.
+#pod
+#pod =cut
+
+sub merged_requirements {
+  my ($self, $phases, $types) = @_;
+  $phases = [qw/runtime build test/] unless defined $phases;
+  $types = [qw/requires recommends/] unless defined $types;
+
+  confess "merged_requirements phases argument must be an arrayref"
+    unless ref $phases eq 'ARRAY';
+  confess "merged_requirements types argument must be an arrayref"
+    unless ref $types eq 'ARRAY';
+
+  my $req = CPAN::Meta::Requirements->new;
+
+  for my $phase ( @$phases ) {
+    unless ($phase =~ /\Ax_/i or grep { $phase eq $_ } $self->__legal_phases) {
+        confess "requested requirements for unknown phase: $phase";
+    }
+    for my $type ( @$types ) {
+      unless ($type =~ /\Ax_/i or grep { $type eq $_ } $self->__legal_types) {
+          confess "requested requirements for unknown type: $type";
+      }
+      $req->add_requirements( $self->requirements_for($phase, $type) );
+    }
+  }
+
+  $req->finalize if $self->is_finalized;
+
+  return $req;
+}
+
+
+#pod =method as_string_hash
+#pod
+#pod This method returns a hashref containing structures suitable for dumping into a
+#pod distmeta data structure.  It is made up of hashes and strings, only; there will
+#pod be no Prereqs, CPAN::Meta::Requirements, or C<version> objects inside it.
+#pod
+#pod =cut
+
+sub as_string_hash {
+  my ($self) = @_;
+
+  my %hash;
+
+  for my $phase ($self->phases) {
+    for my $type ($self->types_in($phase)) {
+      my $req = $self->requirements_for($phase, $type);
+      next unless $req->required_modules;
+
+      $hash{ $phase }{ $type } = $req->as_string_hash;
+    }
+  }
+
+  return \%hash;
+}
+
+#pod =method is_finalized
+#pod
+#pod This method returns true if the set of prereqs has been marked "finalized," and
+#pod cannot be altered.
+#pod
+#pod =cut
+
+sub is_finalized { $_[0]{finalized} }
+
+#pod =method finalize
+#pod
+#pod Calling C<finalize> on a Prereqs object will close it for further modification.
+#pod Attempting to make any changes that would actually alter the prereqs will
+#pod result in an exception being thrown.
+#pod
+#pod =cut
+
+sub finalize {
+  my ($self) = @_;
+
+  $self->{finalized} = 1;
+
+  for my $phase (keys %{ $self->{prereqs} }) {
+    $_->finalize for values %{ $self->{prereqs}{$phase} };
+  }
+}
+
+#pod =method clone
+#pod
+#pod   my $cloned_prereqs = $prereqs->clone;
+#pod
+#pod This method returns a Prereqs object that is identical to the original object,
+#pod but can be altered without affecting the original object.  Finalization does
+#pod not survive cloning, meaning that you may clone a finalized set of prereqs and
+#pod then modify the clone.
+#pod
+#pod =cut
+
+sub clone {
+  my ($self) = @_;
+
+  my $clone = (ref $self)->new( $self->as_string_hash );
+}
+
+sub __uniq {
+  my (%s, $u);
+  grep { defined($_) ? !$s{$_}++ : !$u++ } @_;
+}
+
+1;
+
+# ABSTRACT: a set of distribution prerequisites by phase and type
+
+=pod
+
+=encoding UTF-8
+
+=head1 NAME
+
+CPAN::Meta::Prereqs - a set of distribution prerequisites by phase and type
+
+=head1 VERSION
+
+version 2.150010
+
+=head1 DESCRIPTION
+
+A CPAN::Meta::Prereqs object represents the prerequisites for a CPAN
+distribution or one of its optional features.  Each set of prereqs is
+organized by phase and type, as described in L<CPAN::Meta::Prereqs>.
+
+=head1 METHODS
+
+=head2 new
+
+  my $prereq = CPAN::Meta::Prereqs->new( \%prereq_spec );
+
+This method returns a new set of Prereqs.  The input should look like the
+contents of the C<prereqs> field described in L<CPAN::Meta::Spec>, meaning
+something more or less like this:
+
+  my $prereq = CPAN::Meta::Prereqs->new({
+    runtime => {
+      requires => {
+        'Some::Module' => '1.234',
+        ...,
+      },
+      ...,
+    },
+    ...,
+  });
+
+You can also construct an empty set of prereqs with:
+
+  my $prereqs = CPAN::Meta::Prereqs->new;
+
+This empty set of prereqs is useful for accumulating new prereqs before finally
+dumping the whole set into a structure or string.
+
+=head2 requirements_for
+
+  my $requirements = $prereqs->requirements_for( $phase, $type );
+
+This method returns a L<CPAN::Meta::Requirements> object for the given
+phase/type combination.  If no prerequisites are registered for that
+combination, a new CPAN::Meta::Requirements object will be returned, and it may
+be added to as needed.
+
+If C<$phase> or C<$type> are undefined or otherwise invalid, an exception will
+be raised.
+
+=head2 phases
+
+  my @phases = $prereqs->phases;
+
+This method returns the list of all phases currently populated in the prereqs
+object, suitable for iterating.
+
+=head2 types_in
+
+  my @runtime_types = $prereqs->types_in('runtime');
+
+This method returns the list of all types currently populated in the prereqs
+object for the provided phase, suitable for iterating.
+
+=head2 with_merged_prereqs
+
+  my $new_prereqs = $prereqs->with_merged_prereqs( $other_prereqs );
+
+  my $new_prereqs = $prereqs->with_merged_prereqs( \@other_prereqs );
+
+This method returns a new CPAN::Meta::Prereqs objects in which all the
+other prerequisites given are merged into the current set.  This is primarily
+provided for combining a distribution's core prereqs with the prereqs of one of
+its optional features.
+
+The new prereqs object has no ties to the originals, and altering it further
+will not alter them.
+
+=head2 merged_requirements
+
+    my $new_reqs = $prereqs->merged_requirements( \@phases, \@types );
+    my $new_reqs = $prereqs->merged_requirements( \@phases );
+    my $new_reqs = $prereqs->merged_requirements();
+
+This method joins together all requirements across a number of phases
+and types into a new L<CPAN::Meta::Requirements> object.  If arguments
+are omitted, it defaults to "runtime", "build" and "test" for phases
+and "requires" and "recommends" for types.
+
+=head2 as_string_hash
+
+This method returns a hashref containing structures suitable for dumping into a
+distmeta data structure.  It is made up of hashes and strings, only; there will
+be no Prereqs, CPAN::Meta::Requirements, or C<version> objects inside it.
+
+=head2 is_finalized
+
+This method returns true if the set of prereqs has been marked "finalized," and
+cannot be altered.
+
+=head2 finalize
+
+Calling C<finalize> on a Prereqs object will close it for further modification.
+Attempting to make any changes that would actually alter the prereqs will
+result in an exception being thrown.
+
+=head2 clone
+
+  my $cloned_prereqs = $prereqs->clone;
+
+This method returns a Prereqs object that is identical to the original object,
+but can be altered without affecting the original object.  Finalization does
+not survive cloning, meaning that you may clone a finalized set of prereqs and
+then modify the clone.
+
+=head1 BUGS
+
+Please report any bugs or feature using the CPAN Request Tracker.
+Bugs can be submitted through the web interface at
+L<http://rt.cpan.org/Dist/Display.html?Queue=CPAN-Meta>
+
+When submitting a bug or request, please include a test-file or a patch to an
+existing test-file that illustrates the bug or desired feature.
+
+=head1 AUTHORS
+
+=over 4
+
+=item *
+
+David Golden <dagolden@cpan.org>
+
+=item *
+
+Ricardo Signes <rjbs@cpan.org>
+
+=item *
+
+Adam Kennedy <adamk@cpan.org>
+
+=back
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2010 by David Golden, Ricardo Signes, Adam Kennedy and Contributors.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut
+
+__END__
+
+
+# vim: ts=2 sts=2 sw=2 et :

database/perl/lib/CPAN/Meta/YAML.pm

@@ -0,0 +1,951 @@
+use 5.008001; # sane UTF-8 support
+use strict;
+use warnings;
+package CPAN::Meta::YAML; # git description: v1.68-2-gcc5324e
+# XXX-INGY is 5.8.1 too old/broken for utf8?
+# XXX-XDG Lancaster consensus was that it was sufficient until
+# proven otherwise
+$CPAN::Meta::YAML::VERSION = '0.018';
+; # original $VERSION removed by Doppelgaenger
+
+#####################################################################
+# The CPAN::Meta::YAML API.
+#
+# These are the currently documented API functions/methods and
+# exports:
+
+use Exporter;
+our @ISA       = qw{ Exporter  };
+our @EXPORT    = qw{ Load Dump };
+our @EXPORT_OK = qw{ LoadFile DumpFile freeze thaw };
+
+###
+# Functional/Export API:
+
+sub Dump {
+    return CPAN::Meta::YAML->new(@_)->_dump_string;
+}
+
+# XXX-INGY Returning last document seems a bad behavior.
+# XXX-XDG I think first would seem more natural, but I don't know
+# that it's worth changing now
+sub Load {
+    my $self = CPAN::Meta::YAML->_load_string(@_);
+    if ( wantarray ) {
+        return @$self;
+    } else {
+        # To match YAML.pm, return the last document
+        return $self->[-1];
+    }
+}
+
+# XXX-INGY Do we really need freeze and thaw?
+# XXX-XDG I don't think so.  I'd support deprecating them.
+BEGIN {
+    *freeze = \&Dump;
+    *thaw   = \&Load;
+}
+
+sub DumpFile {
+    my $file = shift;
+    return CPAN::Meta::YAML->new(@_)->_dump_file($file);
+}
+
+sub LoadFile {
+    my $file = shift;
+    my $self = CPAN::Meta::YAML->_load_file($file);
+    if ( wantarray ) {
+        return @$self;
+    } else {
+        # Return only the last document to match YAML.pm,
+        return $self->[-1];
+    }
+}
+
+
+###
+# Object Oriented API:
+
+# Create an empty CPAN::Meta::YAML object
+# XXX-INGY Why do we use ARRAY object?
+# NOTE: I get it now, but I think it's confusing and not needed.
+# Will change it on a branch later, for review.
+#
+# XXX-XDG I don't support changing it yet.  It's a very well-documented
+# "API" of CPAN::Meta::YAML.  I'd support deprecating it, but Adam suggested
+# we not change it until YAML.pm's own OO API is established so that
+# users only have one API change to digest, not two
+sub new {
+    my $class = shift;
+    bless [ @_ ], $class;
+}
+
+# XXX-INGY It probably doesn't matter, and it's probably too late to
+# change, but 'read/write' are the wrong names. Read and Write
+# are actions that take data from storage to memory
+# characters/strings. These take the data to/from storage to native
+# Perl objects, which the terms dump and load are meant. As long as
+# this is a legacy quirk to CPAN::Meta::YAML it's ok, but I'd prefer not
+# to add new {read,write}_* methods to this API.
+
+sub read_string {
+    my $self = shift;
+    $self->_load_string(@_);
+}
+
+sub write_string {
+    my $self = shift;
+    $self->_dump_string(@_);
+}
+
+sub read {
+    my $self = shift;
+    $self->_load_file(@_);
+}
+
+sub write {
+    my $self = shift;
+    $self->_dump_file(@_);
+}
+
+
+
+
+#####################################################################
+# Constants
+
+# Printed form of the unprintable characters in the lowest range
+# of ASCII characters, listed by ASCII ordinal position.
+my @UNPRINTABLE = qw(
+    0    x01  x02  x03  x04  x05  x06  a
+    b    t    n    v    f    r    x0E  x0F
+    x10  x11  x12  x13  x14  x15  x16  x17
+    x18  x19  x1A  e    x1C  x1D  x1E  x1F
+);
+
+# Printable characters for escapes
+my %UNESCAPES = (
+    0 => "\x00", z => "\x00", N    => "\x85",
+    a => "\x07", b => "\x08", t    => "\x09",
+    n => "\x0a", v => "\x0b", f    => "\x0c",
+    r => "\x0d", e => "\x1b", '\\' => '\\',
+);
+
+# XXX-INGY
+# I(ngy) need to decide if these values should be quoted in
+# CPAN::Meta::YAML or not. Probably yes.
+
+# These 3 values have special meaning when unquoted and using the
+# default YAML schema. They need quotes if they are strings.
+my %QUOTE = map { $_ => 1 } qw{
+    null true false
+};
+
+# The commented out form is simpler, but overloaded the Perl regex
+# engine due to recursion and backtracking problems on strings
+# larger than 32,000ish characters. Keep it for reference purposes.
+# qr/\"((?:\\.|[^\"])*)\"/
+my $re_capture_double_quoted = qr/\"([^\\"]*(?:\\.[^\\"]*)*)\"/;
+my $re_capture_single_quoted = qr/\'([^\']*(?:\'\'[^\']*)*)\'/;
+# unquoted re gets trailing space that needs to be stripped
+my $re_capture_unquoted_key  = qr/([^:]+(?::+\S(?:[^:]*|.*?(?=:)))*)(?=\s*\:(?:\s+|$))/;
+my $re_trailing_comment      = qr/(?:\s+\#.*)?/;
+my $re_key_value_separator   = qr/\s*:(?:\s+(?:\#.*)?|$)/;
+
+
+
+
+
+#####################################################################
+# CPAN::Meta::YAML Implementation.
+#
+# These are the private methods that do all the work. They may change
+# at any time.
+
+
+###
+# Loader functions:
+
+# Create an object from a file
+sub _load_file {
+    my $class = ref $_[0] ? ref shift : shift;
+
+    # Check the file
+    my $file = shift or $class->_error( 'You did not specify a file name' );
+    $class->_error( "File '$file' does not exist" )
+        unless -e $file;
+    $class->_error( "'$file' is a directory, not a file" )
+        unless -f _;
+    $class->_error( "Insufficient permissions to read '$file'" )
+        unless -r _;
+
+    # Open unbuffered with strict UTF-8 decoding and no translation layers
+    open( my $fh, "<:unix:encoding(UTF-8)", $file );
+    unless ( $fh ) {
+        $class->_error("Failed to open file '$file': $!");
+    }
+
+    # flock if available (or warn if not possible for OS-specific reasons)
+    if ( _can_flock() ) {
+        flock( $fh, Fcntl::LOCK_SH() )
+            or warn "Couldn't lock '$file' for reading: $!";
+    }
+
+    # slurp the contents
+    my $contents = eval {
+        use warnings FATAL => 'utf8';
+        local $/;
+        <$fh>
+    };
+    if ( my $err = $@ ) {
+        $class->_error("Error reading from file '$file': $err");
+    }
+
+    # close the file (release the lock)
+    unless ( close $fh ) {
+        $class->_error("Failed to close file '$file': $!");
+    }
+
+    $class->_load_string( $contents );
+}
+
+# Create an object from a string
+sub _load_string {
+    my $class  = ref $_[0] ? ref shift : shift;
+    my $self   = bless [], $class;
+    my $string = $_[0];
+    eval {
+        unless ( defined $string ) {
+            die \"Did not provide a string to load";
+        }
+
+        # Check if Perl has it marked as characters, but it's internally
+        # inconsistent.  E.g. maybe latin1 got read on a :utf8 layer
+        if ( utf8::is_utf8($string) && ! utf8::valid($string) ) {
+            die \<<'...';
+Read an invalid UTF-8 string (maybe mixed UTF-8 and 8-bit character set).
+Did you decode with lax ":utf8" instead of strict ":encoding(UTF-8)"?
+...
+        }
+
+        # Ensure Unicode character semantics, even for 0x80-0xff
+        utf8::upgrade($string);
+
+        # Check for and strip any leading UTF-8 BOM
+        $string =~ s/^\x{FEFF}//;
+
+        # Check for some special cases
+        return $self unless length $string;
+
+        # Split the file into lines
+        my @lines = grep { ! /^\s*(?:\#.*)?\z/ }
+                split /(?:\015{1,2}\012|\015|\012)/, $string;
+
+        # Strip the initial YAML header
+        @lines and $lines[0] =~ /^\%YAML[: ][\d\.]+.*\z/ and shift @lines;
+
+        # A nibbling parser
+        my $in_document = 0;
+        while ( @lines ) {
+            # Do we have a document header?
+            if ( $lines[0] =~ /^---\s*(?:(.+)\s*)?\z/ ) {
+                # Handle scalar documents
+                shift @lines;
+                if ( defined $1 and $1 !~ /^(?:\#.+|\%YAML[: ][\d\.]+)\z/ ) {
+                    push @$self,
+                        $self->_load_scalar( "$1", [ undef ], \@lines );
+                    next;
+                }
+                $in_document = 1;
+            }
+
+            if ( ! @lines or $lines[0] =~ /^(?:---|\.\.\.)/ ) {
+                # A naked document
+                push @$self, undef;
+                while ( @lines and $lines[0] !~ /^---/ ) {
+                    shift @lines;
+                }
+                $in_document = 0;
+
+            # XXX The final '-+$' is to look for -- which ends up being an
+            # error later.
+            } elsif ( ! $in_document && @$self ) {
+                # only the first document can be explicit
+                die \"CPAN::Meta::YAML failed to classify the line '$lines[0]'";
+            } elsif ( $lines[0] =~ /^\s*\-(?:\s|$|-+$)/ ) {
+                # An array at the root
+                my $document = [ ];
+                push @$self, $document;
+                $self->_load_array( $document, [ 0 ], \@lines );
+
+            } elsif ( $lines[0] =~ /^(\s*)\S/ ) {
+                # A hash at the root
+                my $document = { };
+                push @$self, $document;
+                $self->_load_hash( $document, [ length($1) ], \@lines );
+
+            } else {
+                # Shouldn't get here.  @lines have whitespace-only lines
+                # stripped, and previous match is a line with any
+                # non-whitespace.  So this clause should only be reachable via
+                # a perlbug where \s is not symmetric with \S
+
+                # uncoverable statement
+                die \"CPAN::Meta::YAML failed to classify the line '$lines[0]'";
+            }
+        }
+    };
+    my $err = $@;
+    if ( ref $err eq 'SCALAR' ) {
+        $self->_error(${$err});
+    } elsif ( $err ) {
+        $self->_error($err);
+    }
+
+    return $self;
+}
+
+sub _unquote_single {
+    my ($self, $string) = @_;
+    return '' unless length $string;
+    $string =~ s/\'\'/\'/g;
+    return $string;
+}
+
+sub _unquote_double {
+    my ($self, $string) = @_;
+    return '' unless length $string;
+    $string =~ s/\\"/"/g;
+    $string =~
+        s{\\([Nnever\\fartz0b]|x([0-9a-fA-F]{2}))}
+         {(length($1)>1)?pack("H2",$2):$UNESCAPES{$1}}gex;
+    return $string;
+}
+
+# Load a YAML scalar string to the actual Perl scalar
+sub _load_scalar {
+    my ($self, $string, $indent, $lines) = @_;
+
+    # Trim trailing whitespace
+    $string =~ s/\s*\z//;
+
+    # Explitic null/undef
+    return undef if $string eq '~';
+
+    # Single quote
+    if ( $string =~ /^$re_capture_single_quoted$re_trailing_comment\z/ ) {
+        return $self->_unquote_single($1);
+    }
+
+    # Double quote.
+    if ( $string =~ /^$re_capture_double_quoted$re_trailing_comment\z/ ) {
+        return $self->_unquote_double($1);
+    }
+
+    # Special cases
+    if ( $string =~ /^[\'\"!&]/ ) {
+        die \"CPAN::Meta::YAML does not support a feature in line '$string'";
+    }
+    return {} if $string =~ /^{}(?:\s+\#.*)?\z/;
+    return [] if $string =~ /^\[\](?:\s+\#.*)?\z/;
+
+    # Regular unquoted string
+    if ( $string !~ /^[>|]/ ) {
+        die \"CPAN::Meta::YAML found illegal characters in plain scalar: '$string'"
+            if $string =~ /^(?:-(?:\s|$)|[\@\%\`])/ or
+                $string =~ /:(?:\s|$)/;
+        $string =~ s/\s+#.*\z//;
+        return $string;
+    }
+
+    # Error
+    die \"CPAN::Meta::YAML failed to find multi-line scalar content" unless @$lines;
+
+    # Check the indent depth
+    $lines->[0]   =~ /^(\s*)/;
+    $indent->[-1] = length("$1");
+    if ( defined $indent->[-2] and $indent->[-1] <= $indent->[-2] ) {
+        die \"CPAN::Meta::YAML found bad indenting in line '$lines->[0]'";
+    }
+
+    # Pull the lines
+    my @multiline = ();
+    while ( @$lines ) {
+        $lines->[0] =~ /^(\s*)/;
+        last unless length($1) >= $indent->[-1];
+        push @multiline, substr(shift(@$lines), length($1));
+    }
+
+    my $j = (substr($string, 0, 1) eq '>') ? ' ' : "\n";
+    my $t = (substr($string, 1, 1) eq '-') ? ''  : "\n";
+    return join( $j, @multiline ) . $t;
+}
+
+# Load an array
+sub _load_array {
+    my ($self, $array, $indent, $lines) = @_;
+
+    while ( @$lines ) {
+        # Check for a new document
+        if ( $lines->[0] =~ /^(?:---|\.\.\.)/ ) {
+            while ( @$lines and $lines->[0] !~ /^---/ ) {
+                shift @$lines;
+            }
+            return 1;
+        }
+
+        # Check the indent level
+        $lines->[0] =~ /^(\s*)/;
+        if ( length($1) < $indent->[-1] ) {
+            return 1;
+        } elsif ( length($1) > $indent->[-1] ) {
+            die \"CPAN::Meta::YAML found bad indenting in line '$lines->[0]'";
+        }
+
+        if ( $lines->[0] =~ /^(\s*\-\s+)[^\'\"]\S*\s*:(?:\s+|$)/ ) {
+            # Inline nested hash
+            my $indent2 = length("$1");
+            $lines->[0] =~ s/-/ /;
+            push @$array, { };
+            $self->_load_hash( $array->[-1], [ @$indent, $indent2 ], $lines );
+
+        } elsif ( $lines->[0] =~ /^\s*\-\s*\z/ ) {
+            shift @$lines;
+            unless ( @$lines ) {
+                push @$array, undef;
+                return 1;
+            }
+            if ( $lines->[0] =~ /^(\s*)\-/ ) {
+                my $indent2 = length("$1");
+                if ( $indent->[-1] == $indent2 ) {
+                    # Null array entry
+                    push @$array, undef;
+                } else {
+                    # Naked indenter
+                    push @$array, [ ];
+                    $self->_load_array(
+                        $array->[-1], [ @$indent, $indent2 ], $lines
+                    );
+                }
+
+            } elsif ( $lines->[0] =~ /^(\s*)\S/ ) {
+                push @$array, { };
+                $self->_load_hash(
+                    $array->[-1], [ @$indent, length("$1") ], $lines
+                );
+
+            } else {
+                die \"CPAN::Meta::YAML failed to classify line '$lines->[0]'";
+            }
+
+        } elsif ( $lines->[0] =~ /^\s*\-(\s*)(.+?)\s*\z/ ) {
+            # Array entry with a value
+            shift @$lines;
+            push @$array, $self->_load_scalar(
+                "$2", [ @$indent, undef ], $lines
+            );
+
+        } elsif ( defined $indent->[-2] and $indent->[-1] == $indent->[-2] ) {
+            # This is probably a structure like the following...
+            # ---
+            # foo:
+            # - list
+            # bar: value
+            #
+            # ... so lets return and let the hash parser handle it
+            return 1;
+
+        } else {
+            die \"CPAN::Meta::YAML failed to classify line '$lines->[0]'";
+        }
+    }
+
+    return 1;
+}
+
+# Load a hash
+sub _load_hash {
+    my ($self, $hash, $indent, $lines) = @_;
+
+    while ( @$lines ) {
+        # Check for a new document
+        if ( $lines->[0] =~ /^(?:---|\.\.\.)/ ) {
+            while ( @$lines and $lines->[0] !~ /^---/ ) {
+                shift @$lines;
+            }
+            return 1;
+        }
+
+        # Check the indent level
+        $lines->[0] =~ /^(\s*)/;
+        if ( length($1) < $indent->[-1] ) {
+            return 1;
+        } elsif ( length($1) > $indent->[-1] ) {
+            die \"CPAN::Meta::YAML found bad indenting in line '$lines->[0]'";
+        }
+
+        # Find the key
+        my $key;
+
+        # Quoted keys
+        if ( $lines->[0] =~
+            s/^\s*$re_capture_single_quoted$re_key_value_separator//
+        ) {
+            $key = $self->_unquote_single($1);
+        }
+        elsif ( $lines->[0] =~
+            s/^\s*$re_capture_double_quoted$re_key_value_separator//
+        ) {
+            $key = $self->_unquote_double($1);
+        }
+        elsif ( $lines->[0] =~
+            s/^\s*$re_capture_unquoted_key$re_key_value_separator//
+        ) {
+            $key = $1;
+            $key =~ s/\s+$//;
+        }
+        elsif ( $lines->[0] =~ /^\s*\?/ ) {
+            die \"CPAN::Meta::YAML does not support a feature in line '$lines->[0]'";
+        }
+        else {
+            die \"CPAN::Meta::YAML failed to classify line '$lines->[0]'";
+        }
+
+        if ( exists $hash->{$key} ) {
+            warn "CPAN::Meta::YAML found a duplicate key '$key' in line '$lines->[0]'";
+        }
+
+        # Do we have a value?
+        if ( length $lines->[0] ) {
+            # Yes
+            $hash->{$key} = $self->_load_scalar(
+                shift(@$lines), [ @$indent, undef ], $lines
+            );
+        } else {
+            # An indent
+            shift @$lines;
+            unless ( @$lines ) {
+                $hash->{$key} = undef;
+                return 1;
+            }
+            if ( $lines->[0] =~ /^(\s*)-/ ) {
+                $hash->{$key} = [];
+                $self->_load_array(
+                    $hash->{$key}, [ @$indent, length($1) ], $lines
+                );
+            } elsif ( $lines->[0] =~ /^(\s*)./ ) {
+                my $indent2 = length("$1");
+                if ( $indent->[-1] >= $indent2 ) {
+                    # Null hash entry
+                    $hash->{$key} = undef;
+                } else {
+                    $hash->{$key} = {};
+                    $self->_load_hash(
+                        $hash->{$key}, [ @$indent, length($1) ], $lines
+                    );
+                }
+            }
+        }
+    }
+
+    return 1;
+}
+
+
+###
+# Dumper functions:
+
+# Save an object to a file
+sub _dump_file {
+    my $self = shift;
+
+    require Fcntl;
+
+    # Check the file
+    my $file = shift or $self->_error( 'You did not specify a file name' );
+
+    my $fh;
+    # flock if available (or warn if not possible for OS-specific reasons)
+    if ( _can_flock() ) {
+        # Open without truncation (truncate comes after lock)
+        my $flags = Fcntl::O_WRONLY()|Fcntl::O_CREAT();
+        sysopen( $fh, $file, $flags );
+        unless ( $fh ) {
+            $self->_error("Failed to open file '$file' for writing: $!");
+        }
+
+        # Use no translation and strict UTF-8
+        binmode( $fh, ":raw:encoding(UTF-8)");
+
+        flock( $fh, Fcntl::LOCK_EX() )
+            or warn "Couldn't lock '$file' for reading: $!";
+
+        # truncate and spew contents
+        truncate $fh, 0;
+        seek $fh, 0, 0;
+    }
+    else {
+        open $fh, ">:unix:encoding(UTF-8)", $file;
+    }
+
+    # serialize and spew to the handle
+    print {$fh} $self->_dump_string;
+
+    # close the file (release the lock)
+    unless ( close $fh ) {
+        $self->_error("Failed to close file '$file': $!");
+    }
+
+    return 1;
+}
+
+# Save an object to a string
+sub _dump_string {
+    my $self = shift;
+    return '' unless ref $self && @$self;
+
+    # Iterate over the documents
+    my $indent = 0;
+    my @lines  = ();
+
+    eval {
+        foreach my $cursor ( @$self ) {
+            push @lines, '---';
+
+            # An empty document
+            if ( ! defined $cursor ) {
+                # Do nothing
+
+            # A scalar document
+            } elsif ( ! ref $cursor ) {
+                $lines[-1] .= ' ' . $self->_dump_scalar( $cursor );
+
+            # A list at the root
+            } elsif ( ref $cursor eq 'ARRAY' ) {
+                unless ( @$cursor ) {
+                    $lines[-1] .= ' []';
+                    next;
+                }
+                push @lines, $self->_dump_array( $cursor, $indent, {} );
+
+            # A hash at the root
+            } elsif ( ref $cursor eq 'HASH' ) {
+                unless ( %$cursor ) {
+                    $lines[-1] .= ' {}';
+                    next;
+                }
+                push @lines, $self->_dump_hash( $cursor, $indent, {} );
+
+            } else {
+                die \("Cannot serialize " . ref($cursor));
+            }
+        }
+    };
+    if ( ref $@ eq 'SCALAR' ) {
+        $self->_error(${$@});
+    } elsif ( $@ ) {
+        $self->_error($@);
+    }
+
+    join '', map { "$_\n" } @lines;
+}
+
+sub _has_internal_string_value {
+    my $value = shift;
+    my $b_obj = B::svref_2object(\$value);  # for round trip problem
+    return $b_obj->FLAGS & B::SVf_POK();
+}
+
+sub _dump_scalar {
+    my $string = $_[1];
+    my $is_key = $_[2];
+    # Check this before checking length or it winds up looking like a string!
+    my $has_string_flag = _has_internal_string_value($string);
+    return '~'  unless defined $string;
+    return "''" unless length  $string;
+    if (Scalar::Util::looks_like_number($string)) {
+        # keys and values that have been used as strings get quoted
+        if ( $is_key || $has_string_flag ) {
+            return qq['$string'];
+        }
+        else {
+            return $string;
+        }
+    }
+    if ( $string =~ /[\x00-\x09\x0b-\x0d\x0e-\x1f\x7f-\x9f\'\n]/ ) {
+        $string =~ s/\\/\\\\/g;
+        $string =~ s/"/\\"/g;
+        $string =~ s/\n/\\n/g;
+        $string =~ s/[\x85]/\\N/g;
+        $string =~ s/([\x00-\x1f])/\\$UNPRINTABLE[ord($1)]/g;
+        $string =~ s/([\x7f-\x9f])/'\x' . sprintf("%X",ord($1))/ge;
+        return qq|"$string"|;
+    }
+    if ( $string =~ /(?:^[~!@#%&*|>?:,'"`{}\[\]]|^-+$|\s|:\z)/ or
+        $QUOTE{$string}
+    ) {
+        return "'$string'";
+    }
+    return $string;
+}
+
+sub _dump_array {
+    my ($self, $array, $indent, $seen) = @_;
+    if ( $seen->{refaddr($array)}++ ) {
+        die \"CPAN::Meta::YAML does not support circular references";
+    }
+    my @lines  = ();
+    foreach my $el ( @$array ) {
+        my $line = ('  ' x $indent) . '-';
+        my $type = ref $el;
+        if ( ! $type ) {
+            $line .= ' ' . $self->_dump_scalar( $el );
+            push @lines, $line;
+
+        } elsif ( $type eq 'ARRAY' ) {
+            if ( @$el ) {
+                push @lines, $line;
+                push @lines, $self->_dump_array( $el, $indent + 1, $seen );
+            } else {
+                $line .= ' []';
+                push @lines, $line;
+            }
+
+        } elsif ( $type eq 'HASH' ) {
+            if ( keys %$el ) {
+                push @lines, $line;
+                push @lines, $self->_dump_hash( $el, $indent + 1, $seen );
+            } else {
+                $line .= ' {}';
+                push @lines, $line;
+            }
+
+        } else {
+            die \"CPAN::Meta::YAML does not support $type references";
+        }
+    }
+
+    @lines;
+}
+
+sub _dump_hash {
+    my ($self, $hash, $indent, $seen) = @_;
+    if ( $seen->{refaddr($hash)}++ ) {
+        die \"CPAN::Meta::YAML does not support circular references";
+    }
+    my @lines  = ();
+    foreach my $name ( sort keys %$hash ) {
+        my $el   = $hash->{$name};
+        my $line = ('  ' x $indent) . $self->_dump_scalar($name, 1) . ":";
+        my $type = ref $el;
+        if ( ! $type ) {
+            $line .= ' ' . $self->_dump_scalar( $el );
+            push @lines, $line;
+
+        } elsif ( $type eq 'ARRAY' ) {
+            if ( @$el ) {
+                push @lines, $line;
+                push @lines, $self->_dump_array( $el, $indent + 1, $seen );
+            } else {
+                $line .= ' []';
+                push @lines, $line;
+            }
+
+        } elsif ( $type eq 'HASH' ) {
+            if ( keys %$el ) {
+                push @lines, $line;
+                push @lines, $self->_dump_hash( $el, $indent + 1, $seen );
+            } else {
+                $line .= ' {}';
+                push @lines, $line;
+            }
+
+        } else {
+            die \"CPAN::Meta::YAML does not support $type references";
+        }
+    }
+
+    @lines;
+}
+
+
+
+#####################################################################
+# DEPRECATED API methods:
+
+# Error storage (DEPRECATED as of 1.57)
+our $errstr    = '';
+
+# Set error
+sub _error {
+    require Carp;
+    $errstr = $_[1];
+    $errstr =~ s/ at \S+ line \d+.*//;
+    Carp::croak( $errstr );
+}
+
+# Retrieve error
+my $errstr_warned;
+sub errstr {
+    require Carp;
+    Carp::carp( "CPAN::Meta::YAML->errstr and \$CPAN::Meta::YAML::errstr is deprecated" )
+        unless $errstr_warned++;
+    $errstr;
+}
+
+
+
+
+#####################################################################
+# Helper functions. Possibly not needed.
+
+
+# Use to detect nv or iv
+use B;
+
+# XXX-INGY Is flock CPAN::Meta::YAML's responsibility?
+# Some platforms can't flock :-(
+# XXX-XDG I think it is.  When reading and writing files, we ought
+# to be locking whenever possible.  People (foolishly) use YAML
+# files for things like session storage, which has race issues.
+my $HAS_FLOCK;
+sub _can_flock {
+    if ( defined $HAS_FLOCK ) {
+        return $HAS_FLOCK;
+    }
+    else {
+        require Config;
+        my $c = \%Config::Config;
+        $HAS_FLOCK = grep { $c->{$_} } qw/d_flock d_fcntl_can_lock d_lockf/;
+        require Fcntl if $HAS_FLOCK;
+        return $HAS_FLOCK;
+    }
+}
+
+
+# XXX-INGY Is this core in 5.8.1? Can we remove this?
+# XXX-XDG Scalar::Util 1.18 didn't land until 5.8.8, so we need this
+#####################################################################
+# Use Scalar::Util if possible, otherwise emulate it
+
+use Scalar::Util ();
+BEGIN {
+    local $@;
+    if ( eval { Scalar::Util->VERSION(1.18); } ) {
+        *refaddr = *Scalar::Util::refaddr;
+    }
+    else {
+        eval <<'END_PERL';
+# Scalar::Util failed to load or too old
+sub refaddr {
+    my $pkg = ref($_[0]) or return undef;
+    if ( !! UNIVERSAL::can($_[0], 'can') ) {
+        bless $_[0], 'Scalar::Util::Fake';
+    } else {
+        $pkg = undef;
+    }
+    "$_[0]" =~ /0x(\w+)/;
+    my $i = do { no warnings 'portable'; hex $1 };
+    bless $_[0], $pkg if defined $pkg;
+    $i;
+}
+END_PERL
+    }
+}
+
+delete $CPAN::Meta::YAML::{refaddr};
+
+1;
+
+# XXX-INGY Doc notes I'm putting up here. Changing the doc when it's wrong
+# but leaving grey area stuff up here.
+#
+# I would like to change Read/Write to Load/Dump below without
+# changing the actual API names.
+#
+# It might be better to put Load/Dump API in the SYNOPSIS instead of the
+# dubious OO API.
+#
+# null and bool explanations may be outdated.
+
+=pod
+
+=encoding UTF-8
+
+=head1 NAME
+
+CPAN::Meta::YAML - Read and write a subset of YAML for CPAN Meta files
+
+=head1 VERSION
+
+version 0.018
+
+=head1 SYNOPSIS
+
+    use CPAN::Meta::YAML;
+
+    # reading a META file
+    open $fh, "<:utf8", "META.yml";
+    $yaml_text = do { local $/; <$fh> };
+    $yaml = CPAN::Meta::YAML->read_string($yaml_text)
+      or die CPAN::Meta::YAML->errstr;
+
+    # finding the metadata
+    $meta = $yaml->[0];
+
+    # writing a META file
+    $yaml_text = $yaml->write_string
+      or die CPAN::Meta::YAML->errstr;
+    open $fh, ">:utf8", "META.yml";
+    print $fh $yaml_text;
+
+=head1 DESCRIPTION
+
+This module implements a subset of the YAML specification for use in reading
+and writing CPAN metadata files like F<META.yml> and F<MYMETA.yml>.  It should
+not be used for any other general YAML parsing or generation task.
+
+NOTE: F<META.yml> (and F<MYMETA.yml>) files should be UTF-8 encoded.  Users are
+responsible for proper encoding and decoding.  In particular, the C<read> and
+C<write> methods do B<not> support UTF-8 and should not be used.
+
+=head1 SUPPORT
+
+This module is currently derived from L<YAML::Tiny> by Adam Kennedy.  If
+there are bugs in how it parses a particular META.yml file, please file
+a bug report in the YAML::Tiny bugtracker:
+L<https://github.com/Perl-Toolchain-Gang/YAML-Tiny/issues>
+
+=head1 SEE ALSO
+
+L<YAML::Tiny>, L<YAML>, L<YAML::XS>
+
+=head1 AUTHORS
+
+=over 4
+
+=item *
+
+Adam Kennedy <adamk@cpan.org>
+
+=item *
+
+David Golden <dagolden@cpan.org>
+
+=back
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2010 by Adam Kennedy.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut
+
+__END__
+
+
+# ABSTRACT: Read and write a subset of YAML for CPAN Meta files
+
+