add github readme

Author: Grinnz

README.pod

@@ -0,0 +1,195 @@
+=pod
+
+=head1 NAME
+
+Perl::MinimumVersion - Find a minimum required version of perl for Perl code
+
+=head1 SYNOPSIS
+
+  # Create the version checking object
+  $object = Perl::MinimumVersion->new( $filename );
+  $object = Perl::MinimumVersion->new( \$source  );
+  $object = Perl::MinimumVersion->new( $ppi_document );
+
+  # Find the minimum version
+  $version = $object->minimum_version;
+
+=head1 DESCRIPTION
+
+C<Perl::MinimumVersion> takes Perl source code and calculates the minimum
+version of perl required to be able to run it. Because it is based on
+L<PPI>, it can do this without having to actually load the code.
+
+Currently it tests both the syntax of your code, and the use of explicit
+version dependencies such as C<require 5.005>.
+
+Future plans are to also add support for tracing module dependencies.
+
+Using C<Perl::MinimumVersion> is dead simple, the synopsis pretty much
+covers it.
+
+The distribution comes with a script called L<perlver>,
+which is the easiest way to run C<Perl::MinimumVersion> on your code:
+
+ % perlver lib/Foo/Bar.pm
+
+See the L<documentation for perlver|perlver> for more details.
+
+=head1 METHODS
+
+=head2 new
+
+  # Create the version checking object
+  $object = Perl::MinimumVersion->new( $filename );
+  $object = Perl::MinimumVersion->new( \$source  );
+  $object = Perl::MinimumVersion->new( $ppi_document );
+
+The C<new> constructor creates a new version checking object for a
+L<PPI::Document>. You can also provide the document to be read as a
+file name, or as a C<SCALAR> reference containing the code.
+
+Returns a new C<Perl::MinimumVersion> object, or C<undef> on error.
+
+=head2 Document
+
+The C<Document> accessor can be used to get the L<PPI::Document> object
+back out of the version checker.
+
+=head2 minimum_version
+
+The C<minimum_version> method is the primary method for finding the
+minimum perl version required based on C<all> factors in the document.
+
+At the present time, this is just syntax and explicit version checks,
+as L<Perl::Depends> is not yet completed.
+
+Returns a L<version> object, or C<undef> on error.
+
+=head2 minimum_explicit_version
+
+The C<minimum_explicit_version> method checks through Perl code for the
+use of explicit version dependencies such as.
+
+  use 5.006;
+  require 5.005_03;
+
+Although there is almost always only one of these in a file, if more than
+one are found, the highest version dependency will be returned.
+
+Returns a L<version> object, false if no dependencies could be found,
+or C<undef> on error.
+
+=head2 minimum_syntax_version $limit
+
+The C<minimum_syntax_version> method will explicitly test only the
+Document's syntax to determine it's minimum version, to the extent
+that this is possible.
+
+It takes an optional parameter of a L<version> object defining the
+the lowest known current value. For example, if it is already known
+that it must be 5.006 or higher, then you can provide a param of
+qv(5.006) and the method will not run any of the tests below this
+version. This should provide dramatic speed improvements for
+large and/or complex documents.
+
+The limitations of parsing Perl mean that this method may provide
+artifically low results, but should not artificially high results.
+
+For example, if C<minimum_syntax_version> returned 5.006, you can be
+confident it will not run on anything lower, although there is a chance
+that during actual execution it may use some untestable feature that
+creates a dependency on a higher version.
+
+Returns a L<version> object, false if no dependencies could be found,
+or C<undef> on error.
+
+=head2 minimum_external_version
+
+B<WARNING: This method has not been implemented. Any attempted use will throw
+an exception>
+
+The C<minimum_external_version> examines code for dependencies on other
+external files, and recursively traverses the dependency tree applying the
+same tests to those files as it does to the original.
+
+Returns a C<version> object, false if no dependencies could be found, or
+C<undef> on error.
+
+=head2 version_markers
+
+This method returns a list of pairs in the form:
+
+  ($version, \@markers)
+
+Each pair represents all the markers that could be found indicating that the
+version was the minimum needed version.  C<@markers> is an array of strings.
+Currently, these strings are not as clear as they might be, but this may be
+changed in the future.  In other words: don't rely on them as specific
+identifiers.
+
+=head1 BUGS
+
+B<Perl::MinimumVersion> does a reasonable job of catching the best-known
+explicit version dependencies.
+
+B<However> it is exceedingly easy to add a new syntax check, so if you
+find something this is missing, copy and paste one of the existing
+5 line checking functions, modify it to find what you want, and report it
+to rt.cpan.org, along with the version needed.
+
+I don't even need an entire diff... just the function and version.
+
+=head1 TO DO
+
+B<Write lots more version checkers>
+
+- Perl 5.10 operators and language structures
+
+- Three-argument open
+
+B<Write the explicit version checker>
+
+B<Write the recursive module descend stuff>
+
+_while_readdir for postfix while without brackets
+
+B<Check for more 5.12 features (currently only detecting
+C<package NAME VERSION;>, C<...>, and C<use feature ':5.12'>)>
+
+=head1 SUPPORT
+
+All bugs should be filed via the CPAN bug tracker at
+
+L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Perl-MinimumVersion>
+
+For other issues, or commercial enhancement or support, contact the author.
+
+=head1 AUTHORS
+
+Adam Kennedy E<lt>[email protected]<gt>
+
+=head1 SEE ALSO
+
+L<perlver> - the command-line script for running C<Perl::MinimumVersion>
+on your code.
+
+L<Perl::MinimumVersion::Fast> - another module which does the same thing.
+It's a lot faster, but only supports Perl 5.8.1+.
+
+L<http://ali.as/>, L<PPI>, L<version>
+
+=head1 REPOSITORY
+
+L<https://github.com/neilbowers/Perl-MinimumVersion>
+
+=head1 COPYRIGHT
+
+Copyright 2005 - 2014 Adam Kennedy.
+
+This program is free software; you can redistribute
+it and/or modify it under the same terms as Perl itself.
+
+The full text of the license can be found in the
+LICENSE file included with this module.
+
+=cut

dist.ini

@@ -12,3 +12,9 @@ ExecDir.dir = script
 [PkgVersion]
 [AutoPrereqs]
 [GithubMeta]
+[ReadmeAnyFromPod]
+type = pod
+location = root
+phase = release
+[Regenerate::AfterReleasers]
+plugin = ReadmeAnyFromPod