Pod-Readme-v1.2.3/0000775000175000017500000000000013366431456011465 5ustar rrrrPod-Readme-v1.2.3/MANIFEST0000644000175000017500000000166213366431456012621 0ustar rrrr# This file was automatically generated by Dist::Zilla::Plugin::Manifest v6.012. Changes INSTALL LICENSE MANIFEST MANIFEST.SKIP META.json META.yml Makefile.PL README.pod bin/pod2readme cpanfile dist.ini lib/Pod/Readme.pm lib/Pod/Readme/Filter.pm lib/Pod/Readme/Plugin.pm lib/Pod/Readme/Plugin/changes.pm lib/Pod/Readme/Plugin/requires.pm lib/Pod/Readme/Plugin/version.pm lib/Pod/Readme/Types.pm t/00-report-prereqs.dd t/00-report-prereqs.t t/10-pod-readme-filter.t t/20-pod-readme.t t/author-clean-namespaces.t t/author-critic.t t/author-eof.t t/author-eol.t t/author-minimum-version.t t/author-no-tabs.t t/author-pod-syntax.t t/author-portability.t t/data/META-1.yml t/data/README-1.pod t/data/README.txt t/lib/Pod/Readme/Plugin/noop.pm t/lib/Pod/Readme/Test.pm t/lib/Pod/Readme/Test/Kit.pm t/plugins/changes.t t/plugins/requires.t t/plugins/version.t t/release-check-manifest.t t/release-fixme.t t/release-kwalitee.t t/release-trailing-space.t Pod-Readme-v1.2.3/Makefile.PL0000644000175000017500000000460413366431456013441 0ustar rrrr# This file was automatically generated by Dist::Zilla::Plugin::MakeMaker v6.012. use strict; use warnings; use 5.010001; use ExtUtils::MakeMaker; my %WriteMakefileArgs = ( "ABSTRACT" => "Intelligently generate a README file from POD", "AUTHOR" => "Robert Rothenberg ", "CONFIGURE_REQUIRES" => {}, "DISTNAME" => "Pod-Readme", "EXE_FILES" => [ "bin/pod2readme" ], "LICENSE" => "perl", "MIN_PERL_VERSION" => "5.010001", "NAME" => "Pod::Readme", "PREREQ_PM" => { "CPAN::Changes" => "0.30", "CPAN::Meta" => 0, "Class::Method::Modifiers" => 0, "File::Slurp" => 0, "Getopt::Long::Descriptive" => 0, "Hash::Util" => 0, "List::Util" => "1.33", "Module::CoreList" => 0, "Moo" => 0, "Moo::Role" => 0, "MooX::HandlesVia" => 0, "Path::Tiny" => 0, "Pod::Simple" => 0, "Role::Tiny" => 0, "Scalar::Util" => 0, "Try::Tiny" => 0, "Type::Tiny" => "1.000000", "Types::Standard" => 0, "namespace::autoclean" => 0 }, "TEST_REQUIRES" => { "Cwd" => 0, "File::Compare" => 0, "File::Spec" => 0, "IO::String" => 0, "Module::Metadata" => 0, "Pod::Simple::Text" => 0, "Test::Deep" => 0, "Test::Exception" => 0, "Test::Kit" => 0, "Test::More" => 0 }, "VERSION" => "v1.2.3", "test" => { "TESTS" => "t/*.t t/plugins/*.t" } ); my %FallbackPrereqs = ( "CPAN::Changes" => "0.30", "CPAN::Meta" => 0, "Class::Method::Modifiers" => 0, "Cwd" => 0, "File::Compare" => 0, "File::Slurp" => 0, "File::Spec" => 0, "Getopt::Long::Descriptive" => 0, "Hash::Util" => 0, "IO::String" => 0, "List::Util" => "1.33", "Module::CoreList" => 0, "Module::Metadata" => 0, "Moo" => 0, "Moo::Role" => 0, "MooX::HandlesVia" => 0, "Path::Tiny" => 0, "Pod::Simple" => 0, "Pod::Simple::Text" => 0, "Role::Tiny" => 0, "Scalar::Util" => 0, "Test::Deep" => 0, "Test::Exception" => 0, "Test::Kit" => 0, "Test::More" => 0, "Try::Tiny" => 0, "Type::Tiny" => "1.000000", "Types::Standard" => 0, "namespace::autoclean" => 0 ); unless ( eval { ExtUtils::MakeMaker->VERSION(6.63_03) } ) { delete $WriteMakefileArgs{TEST_REQUIRES}; delete $WriteMakefileArgs{BUILD_REQUIRES}; $WriteMakefileArgs{PREREQ_PM} = \%FallbackPrereqs; } delete $WriteMakefileArgs{CONFIGURE_REQUIRES} unless eval { ExtUtils::MakeMaker->VERSION(6.52) }; WriteMakefile(%WriteMakefileArgs); Pod-Readme-v1.2.3/META.yml0000644000175000017500000000502113366431456012732 0ustar rrrr--- abstract: 'Intelligently generate a README file from POD' author: - 'Robert Rothenberg ' build_requires: Cwd: '0' File::Compare: '0' File::Spec: '0' IO::String: '0' Module::Metadata: '0' Pod::Simple::Text: '0' Test::Deep: '0' Test::Exception: '0' Test::Kit: '0' Test::More: '0' dynamic_config: 0 generated_by: 'Dist::Zilla version 6.012, CPAN::Meta::Converter version 2.150010' keywords: - Moo - data-driven - development - testing license: perl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: '1.4' name: Pod-Readme provides: Pod::Readme: file: lib/Pod/Readme.pm version: v1.2.3 Pod::Readme::Filter: file: lib/Pod/Readme/Filter.pm version: v1.2.3 Pod::Readme::Plugin: file: lib/Pod/Readme/Plugin.pm version: v1.2.3 Pod::Readme::Plugin::changes: file: lib/Pod/Readme/Plugin/changes.pm version: v1.2.3 Pod::Readme::Plugin::requires: file: lib/Pod/Readme/Plugin/requires.pm version: v1.2.3 Pod::Readme::Plugin::version: file: lib/Pod/Readme/Plugin/version.pm version: v1.2.3 Pod::Readme::Types: file: lib/Pod/Readme/Types.pm version: v1.2.3 recommends: Pod::Man: '0' Pod::Markdown: '0' Pod::Markdown::Github: '0' Pod::Simple::HTML: '0' Pod::Simple::LaTeX: '0' Pod::Simple::RTF: '0' Pod::Simple::Text: '0' Pod::Simple::XHTML: '0' Type::Tiny::XS: '0' requires: CPAN::Changes: '0.30' CPAN::Meta: '0' Class::Method::Modifiers: '0' File::Slurp: '0' Getopt::Long::Descriptive: '0' Hash::Util: '0' List::Util: '1.33' Module::CoreList: '0' Moo: '0' Moo::Role: '0' MooX::HandlesVia: '0' Path::Tiny: '0' Pod::Simple: '0' Role::Tiny: '0' Scalar::Util: '0' Try::Tiny: '0' Type::Tiny: '1.000000' Types::Standard: '0' namespace::autoclean: '0' perl: v5.10.1 resources: bugtracker: https://github.com/bigpresh/Pod-Readme/issues homepage: http://search.cpan.org/dist/Pod-Readme repository: git://github.com/bigpresh/Pod-Readme.git version: v1.2.3 x_authority: cpan:RRWO x_contributors: - 'David A. Desrosiers ' - 'David Precious ' - 'Ivan Bessarabov ' - 'Karen Etheridge ' - 'Karl Williamson ' - 'Lucas Kanashiro ' - 'Mohammad S Anwar ' - 'Sergey Romanov ' - 'Yanick Champoux ' x_generated_by_perl: v5.26.1 x_serialization_backend: 'YAML::Tiny version 1.70' Pod-Readme-v1.2.3/bin/0000775000175000017500000000000013366431456012235 5ustar rrrrPod-Readme-v1.2.3/bin/pod2readme0000644000175000017500000001111113366431456014173 0ustar rrrr#!/usr/bin/env perl use v5.10.1; use strict; use warnings; use File::Copy qw/ copy /; use Getopt::Long::Descriptive; use IO::Handle; use Pod::Readme; our $VERSION = 'v1.2.3'; =head1 NAME pod2readme - Intelligently generate a README file from POD =head1 USAGE pod2readme [-cfho] [long options...] input-file [output-file] [target] Intelligently generate a README file from POD -t --target target type (default: 'readme') -f --format output format (default: 'text') -b --backup backup output file -o --output output filename (default based on target) -c --stdout output to stdout (console) -F --force only update if files are changed -h --help print usage and exit =head1 SYNOPSIS pod2readme -f markdown lib/MyApp.pm =head1 DESCRIPTION This utility will use L to extract a F file from a POD document. It works by extracting and filtering the POD, and then calling the appropriate filter program to convert the POD to another format. =head1 OPTIONS =head2 C<--backup> By default, C will back up the output file. To disable this, use the C<--no-backup> option. =head2 C<--output> Specifies the name of the output file. If omitted, it will use the second command line argument, or default to the C<--target> plus the corresponding extension of the C<--format>. For all intents, the default is F. If a format other than "text" is chosen, then the appropriate extension will be added, e.g. for "markdown", the default output file is F. =head2 C<--target> The target of the filter, which defaults to "readme". =head2 C<--format> The output format, which defaults to "text". Other supposed formats are "github", "html", "latex", "man", "markdown", "pod", "rtf", and "xhtml". You can also use "gfm" instead of "github". Similary you can use "md" for "markdown". =head2 C<--stdout> If enabled, it will output to the console instead of C<--output>. =head2 C<--force> By default, the F will be generated if the source files have been changed. Using C<--force> will force the file to be updated. Note: POD format files will always be updated. =head2 C<--help> Prints the usage and exits. =head1 SEE ALSO L, L. =cut my %FORMATS = ( 'gfm' => { class => 'Pod::Markdown::Github' }, 'github' => { class => 'Pod::Markdown::Github' }, 'html' => { class => 'Pod::Simple::HTML', }, 'latex' => { class => 'Pod::Simple::LaTeX' }, 'man' => { class => 'Pod::Man' }, 'markdown' => { class => 'Pod::Markdown' }, 'md' => { class => 'Pod::Markdown' }, 'pod' => { class => undef }, 'rtf' => { class => 'Pod::Simple::RTF' }, 'text' => { class => 'Pod::Simple::Text' }, 'xhtml' => { class => 'Pod::Simple::XHTML' }, ); sub validate_format { my $value = shift; if ( exists $FORMATS{$value} ) { return $value; } else { die "Invalid format: '${value}'\n"; } } my ( $opt, $usage ) = describe_options( '%c %o input-file [output-file] [target]', [], ['Intelligently generate a README file from POD'], [], [ 'target|t=s' => "target type (default: 'readme')" ], [ 'format|f=s' => "output format (default: 'text')", { default => 'text', callbacks => { format => \&validate_format }, } ], [ 'backup|b!' => "backup output file", { default => 1 } ], [ 'output|o' => "output filename (default based on target)" ], [ 'stdout|c' => "output to stdout (console)" ], [ 'force|F!' => "only update if files are changed" ], [ 'help|h' => "print usage and exit" ], ); die $usage if $opt->help; my %args = ( force => $opt->force ); if ( my $input = shift @ARGV ) { $args{input_file} = $input; } my $format = $FORMATS{ $opt->format }; unless ($format) { say sprintf( "Unknown format: '\%s'", $opt->format ); die $usage; } my $output = $opt->output || shift @ARGV; my $target = $opt->target || shift @ARGV || 'readme'; $args{target} = $target; if ( my $class = $format->{class} ) { $args{translation_class} = $class; } if ( $opt->stdout ) { my $fh = IO::Handle->new; if ( $fh->fdopen( fileno(STDOUT), 'w' ) ) { $args{translate_to_fh} = $fh; } else { die "Cannot get a filehandle for STDOUT"; } } else { $args{translate_to_file} = $output if $output; } my $pr = Pod::Readme->new(%args); $output ||= $pr->translate_to_file; if ( $opt->backup && $output && -e $output ) { copy( $output, $output . '.bak' ); } $pr->run(); Pod-Readme-v1.2.3/dist.ini0000644000175000017500000000523013366431456013127 0ustar rrrrname = Pod-Readme author = Robert Rothenberg license = Perl_5 copyright_holder = Robert Rothenberg copyright_year = 2018 [Keywords] keyword = Moo keyword = data-driven keyword = development keyword = testing [Meta::Contributors] contributor = David A. Desrosiers contributor = David Precious contributor = Ivan Bessarabov contributor = Karen Etheridge contributor = Karl Williamson contributor = Lucas Kanashiro contributor = Mohammad S Anwar contributor = Sergey Romanov contributor = Yanick Champoux [GatherDir] exclude_match = cpanfile* exclude_filename = MANIFEST.SKIP [PruneCruft] [CPANFile] [License] [ExtraTests] [ExecDir] [ShareDir] [MakeMaker] [Manifest] [TestRelease] [ConfirmRelease] [UploadToCPAN] [RecommendedPrereqs] [AutoPrereqs] [RemovePrereqs] remove = strict remove = warnings remove = lib remove = feature remove = Carp remove = Exporter remove = ExtUtils::MakeMaker remove = File::Copy remove = File::Spec remove = File::Temp remove = IO remove = IO::Handle remove = Module::Load [EnsurePrereqsInstalled] :version = 0.003 type = requires type = recommends [GitHub::Meta] repo = git://github.com/bigpresh/Pod-Readme.git ;;[PodWeaver] [ReadmeFromPod] type = pod filename = README.pod location = build [CopyFilesFromBuild] copy = README.pod copy = cpanfile copy = MANIFEST.SKIP [Generate::ManifestSkip] [PruneFiles] match = ~$ [Metadata] x_authority = cpan:RRWO [MetaProvides::Package] [MetaJSON] [MetaYAML] [InstallGuide] [Prereqs / TestRequires ] ; authordep Pod::Weaver::Plugin::AppendPrepend ; authordep Pod::Weaver::Section::Contributors ; authordep Pod::Weaver::Section::SourceGitHub [PodSyntaxTests] [Test::CheckManifest] [Test::CleanNamespaces] skip = Pod::Readme::Types [Test::EOF] [Test::EOL] :version = 0.14 [Test::Fixme] [Test::MinimumVersion] [Test::NoTabs] [Test::Perl::Critic] critic_config = t/etc/perlcritic.rc ;;[Test::Pod::Coverage::Configurable] ;;[Test::Pod::LinkCheck] [Test::Portability] ; authordep Test::TrailingSpace [Test::TrailingSpace] filename_regex = \.(?:p[lm])\z [Test::Kwalitee] [Test::ReportPrereqs] :version = 0.022 version_extractor = Module::Metadata verify_prereqs = 1 [@Git] allow_dirty = dist.ini push_to = origin master:master tag_format = %v commit_msg = %v%n%n%c [Git::Contributors] :version = 0.019 [RewriteVersion] [NextRelease] [BumpVersionAfterRelease] [Git::Commit / Commit_Changes] ; commit Changes (for new dev) allow_dirty_match = ^lib/ commit_msg = Commit Changes and bump $VERSION Pod-Readme-v1.2.3/Changes0000644000175000017500000002247613366431456012771 0ustar rrrrRevision history for Pod-Readme v1.2.3 2018-10-31 22:56:42+00:00 Europe/London [Bug Fixes] - Increased minimum version of Type::Tiny to 1.000000. v1.2.2 2018-10-31 22:41:45+00:00 Europe/London [Documentation] - Updated POD with regard to format types (Mohammad S Anwar). - Fixed typos in Changes. [Bug Fixes] - Added explicit requirements for Pod::Simple as well as recommended modules. [Toolchain] - Remove explicit core dependencies from prereqs list. - Updated list of contributors in distribution metadata. (Apologies if anyone was omitted.) v1.2.1 2018-10-30 18:23:48+00:00 Europe/London [Documentation] - Added note about Github Flavoured Markdown (GFM) support to Changes for v1.2.0. [Other] - Restore license to "Perl_5" that was inadvertently changed in the conversion to use Dist::Zilla, GH#25. v1.2.0 2018-10-29 19:24:01+00:00 Europe/London [Bug Fixes] - Specify minimum version of List::Util, GH#22. [Enhancements] - Added "md" as an alias for "markdown" in pod2readme. - Added "github" or "gfm" for Github Flavored Markdown in pod2readme, GH#15. [Incompatabilities] - Removed DistZilla type from Pod::Readme::Types, as it was not necessary. [Toolchain] - Remove use of Module::Install, fixes GH#21. - Use Dist::Zilla to build the distribution. v1.1.2 2014-12-09 18:55 GMT [Bug Fixes] - Regex in changes plugin fixed to work with Perl 5.21 deprecated syntax [khwilliamson]. v1.1.1 2014-12-04 13:11 GMT [Bug Fixes] - The changes plugin will work with Dist::Zilla v1.2.3 2018-10-31 22:56:42+00:00 Europe/London tokens. v1.1.0 2014-12-03 19:08 GMT [Documentation] - Fixed typos in POD for requires plugin. [Enhancements] - Pod::Readme::Filter has a zilla attribute for Dist::Zilla objects. - The requires plugin will use metadata from the Dist::Zilla object if it is set, rather than looking for a META.yml file (which will not exist, if this is used in a Dist::Zilla plugin). v1.0.3 2014-11-07 18:58 GMT - Fixed bug with minimum version of Class::Method::Modifiers. v1.0.2 2014-10-13 22:18 BST - No changes since v1.0.1_08, just a version bump for a release. - See the full list of changes since v1.0.0 for more details. [Enhancements] - This is a complete rewrite, using modern Perl with Moo. - Added support for plugins, along with plugins to insert the module version, prerequisites and the latest changes. - Added the ability to generate a README in a variety of formats, such as POD, Markdown, HTML, RTF, etc. - Added command-line options to the pod2readme script, including the ability to specify the output format. - Switched to semantic versioning. - The documentation has been updated accordingly. [Incompatabilities] - Perl v5.10.1 is required. - This is no longer a subclass of a POD parser, although it has some wrapper methods for compatability with software known to use it. v1.0.1_08 2014-10-13 [Documentation] - More documentation tweaks. v1.0.1_07 2014-10-10 16:47 BST [Documentation] - More documentation tweaks. [Enhancements] - Added a depends_on method that returns a list of files that the README depends on. - Added dependencies_updated method to check if dependencies have been updated. - The README is only updated if dependencies have been updated. - Added a --force option to pod2readme to force updates. [Other Changes] - Moved pod2readme tests to xt directory for author tests, due to inconsistent behaviour on different platforms. v1.0.1_06 2014-10-10 [Documentation] - More documentation tweaks. - Changed pod2readme usage text to match abstract. [Bug Fixes] - Added minimum Perl version to Makefile.PL. - Removed use of Path::Class in pod2readme utility. [Other Changes] - Added rudimentary tests for pod2readme script. [Enhancements] - The requires plugin uses minimum module versions to check if a module is in the core-list. v1.0.1_05 2014-10-09 19:36 BST [Documentation] - Corrected typos in POD. [Bug Fixes] - Disabled use of Test::Kit, since it seems to have problems with Test::Builder 1.301001_056. v1.0.1_04 2014-10-08 23:27 BST [Documentation] - Changed abstract to make the module's purpose more obvious. [Bug Fixes] - Added missing IO::String prereq to tests. v1.0.1_03 2014-10-08 22:42 BST [Documentation] - Added Acknowledgements section to POD. [Bug Fixes] - Added minimum version prereq of Moo to fix issue with undef defaults. [Enhancements] - Changed to use Path::Tiny instead of Path::Class. - Reverted back to using Exporter, since most core modules already use it. v1.0.1_02 2014-10-08 00:49 BST [Documentation] - Added missing timestamp to Changes. - Updated README.pod. [Other Changes] - Changed how versions are defined in modules, to handle quirks of namespace::autoclean. - Changed to use Exporter::Lite. v1.0.1_01 2014-10-08 00:26 BST [Bug Fixes] - Fixed argument name for include command. - Changed tests to compare files so they handle different Windows line endings. [Documentation] - Fixed POD errors and typos. [Enhancements] - Switched to use Type::Tiny-based types, with stricter constraints. - Switched to use Moo instead of Moose. [Other Changes] - Minor internal code tweaks. v1.0.0_03 2014-09-24 21:14 BST [Bug Fixes] - The tests for the requires plugin handle non-author builds. - Fix for tests on some systems. [Enhancements] - Show path of missing META.yml file in requires plugin. [Documentation] - Consistent names in POD. - Fixed typos in Changes file. [Other Changes] - Added hooks for author tests in Makefile.PL. - Fixed license metadata error to make CPANTS happy, and to be consistent with license in the POD. - Tests use Exporter instead of Exporter::Lite. - Tests use Test::Kit rather than Test::Most, and explicitly import the tests modules that they use. - Removed redundant prereqs from Makefile.PL. v1.0.0_02 2014-09-24 14:14 BST [Bug Fixes] - Fixed minimum version of some prerequisites for tests. [Enhancements] - Added parse_from_file and parse_from_filehandle methods for backwards compatability. [Other Changes] - Added more tests. - The bugtracker URL now refers to the GitHub issues list at https://github.com/bigpresh/Pod-Readme/issues instead of RT. - Added a version to all modules in the distribution, and a version QA test to the repo. [Documentation] - Added missing date to Changes. - Fixed typos in POD and README. - Added stub POD to Pod::Readme::Filter. - Fixed a daft typo in the Changes file. - Documented known issue in the requires plugin. - The README is now a POD document. v1.0.0_01 2014-09-23 13:58 BST [Incompatabilities] - Major rewrite, using modern Perl v5.10.1. - This module is no longer a subclass of a POD parsing module. Instead, it is a simple POD filter. [New Features] - Added support for plugins. - Added a "changes" plugin for parsing Changes files. - Added a "version" plugin for including the current version. - Added a "requires" plugin for listing module requirements. - The pod2readme script has been rewritten to take a variety of options, and can generate various formats, such as HTML, Markdown, POD or RTF. [Documentation] - Changes rewritten to conform to CPAN::Changes::Spec. - README is now in Markdown format. [Other Changes] - Switched to semantic versioning. - Added MANIFEST.SKIP to distribution. - QA tests are no longer part of the distribution. - Makefile.PL uses Module::Install. 0.11 2010-12-09 - Recognise the =encoding directive, rather than dying when it's encountered. TODO: actually take heed of it. Thanks to Ivan Bessarabov for bringing this to my attention! 0.10 2010-05-19 - David Precious taking over maintainership - Apply POD fix patch from RT #38328, thanks to David A. Desrosiers 0.09 2006-11-25 - uses Regexp::Common for URI parsing for L<> tag - added separate check for https, ftps, and svn URIs (rt.cpan.org bugs 23585 and 23613) 0.081 2006-05-07 - released package without signature, due to Module::Signature issues 0.08 2006-05-01 - head3/4 headings now recognized - went back to using Pod::PlainText 0.07 2006-02-11 - added min version to use Pod::Text statement in source - removed multiple plans from the podcover test 0.06 2006-02-09 - eliminated a warning about uninitialized values - recognizes =head3 and =head4 headings (from Pod::Text) - uses Pod::Text instead of Pod::PlainText - added internal documentation - added various QA tests - added "test" and "tests" as a rejected format 0.05 2005-06-07 - pod2readme will backup an existing README file - minor updates to the documentation 0.04 2005-05-18 - known other formats such as "html" are rejected - added missing prereq IO::File in Build.PL - added debug option - typos and tweaks for documentation 0.03 2005-05-08 - added documentation to pod2readme script - include file start/stop marks are now Regexps - added more tests - multiple readme types can be specified in a command 0.02 2005-05-06 - added tests (much needed!) - fixed issue with links being changed to refer to manpages 0.01 2005-04-20 - original version Pod-Readme-v1.2.3/cpanfile0000644000175000017500000000352513366431456013174 0ustar rrrrrequires "CPAN::Changes" => "0.30"; requires "CPAN::Meta" => "0"; requires "Class::Method::Modifiers" => "0"; requires "File::Slurp" => "0"; requires "Getopt::Long::Descriptive" => "0"; requires "Hash::Util" => "0"; requires "List::Util" => "1.33"; requires "Module::CoreList" => "0"; requires "Moo" => "0"; requires "Moo::Role" => "0"; requires "MooX::HandlesVia" => "0"; requires "Path::Tiny" => "0"; requires "Pod::Simple" => "0"; requires "Role::Tiny" => "0"; requires "Scalar::Util" => "0"; requires "Try::Tiny" => "0"; requires "Type::Tiny" => "1.000000"; requires "Types::Standard" => "0"; requires "namespace::autoclean" => "0"; requires "perl" => "v5.10.1"; recommends "Pod::Man" => "0"; recommends "Pod::Markdown" => "0"; recommends "Pod::Markdown::Github" => "0"; recommends "Pod::Simple::HTML" => "0"; recommends "Pod::Simple::LaTeX" => "0"; recommends "Pod::Simple::RTF" => "0"; recommends "Pod::Simple::Text" => "0"; recommends "Pod::Simple::XHTML" => "0"; recommends "Type::Tiny::XS" => "0"; on 'test' => sub { requires "Cwd" => "0"; requires "File::Compare" => "0"; requires "File::Spec" => "0"; requires "IO::String" => "0"; requires "Module::Metadata" => "0"; requires "Pod::Simple::Text" => "0"; requires "Test::Deep" => "0"; requires "Test::Exception" => "0"; requires "Test::Kit" => "0"; requires "Test::More" => "0"; }; on 'test' => sub { recommends "CPAN::Meta" => "2.120900"; }; on 'develop' => sub { requires "Test::CleanNamespaces" => "0.15"; requires "Test::EOF" => "0"; requires "Test::EOL" => "0"; requires "Test::Kwalitee" => "1.21"; requires "Test::MinimumVersion" => "0"; requires "Test::More" => "0.88"; requires "Test::NoTabs" => "0"; requires "Test::Perl::Critic" => "0"; requires "Test::Pod" => "1.41"; requires "Test::Portability::Files" => "0"; requires "Test::TrailingSpace" => "0.0203"; }; Pod-Readme-v1.2.3/INSTALL0000644000175000017500000000302413366431456012513 0ustar rrrrThis is the Perl distribution Pod-Readme. Installing Pod-Readme is straightforward. ## Installation with cpanm If you have cpanm, you only need one line: % cpanm Pod::Readme If it does not have permission to install modules to the current perl, cpanm will automatically set up and install to a local::lib in your home directory. See the local::lib documentation (https://metacpan.org/pod/local::lib) for details on enabling it in your environment. ## Installing with the CPAN shell Alternatively, if your CPAN shell is set up, you should just be able to do: % cpan Pod::Readme ## Manual installation As a last resort, you can manually install it. Download the tarball, untar it, then build it: % perl Makefile.PL % make && make test Then install it: % make install On Windows platforms, you should use `dmake` or `nmake`, instead of `make`. If your perl is system-managed, you can create a local::lib in your home directory to install modules to. For details, see the local::lib documentation: https://metacpan.org/pod/local::lib The prerequisites of this distribution will also have to be installed manually. The prerequisites are listed in one of the files: `MYMETA.yml` or `MYMETA.json` generated by running the manual build process described above. ## Documentation Pod-Readme documentation is available as POD. You can run `perldoc` from a shell to read the documentation: % perldoc Pod::Readme For more information on installing Perl modules via CPAN, please see: https://www.cpan.org/modules/INSTALL.html Pod-Readme-v1.2.3/t/0000775000175000017500000000000013366431456011730 5ustar rrrrPod-Readme-v1.2.3/t/release-kwalitee.t0000644000175000017500000000050413366431456015335 0ustar rrrr BEGIN { unless ($ENV{RELEASE_TESTING}) { print qq{1..0 # SKIP these tests are for release candidate testing\n}; exit } } # this test was generated with Dist::Zilla::Plugin::Test::Kwalitee 2.12 use strict; use warnings; use Test::More 0.88; use Test::Kwalitee 1.21 'kwalitee_ok'; kwalitee_ok(); done_testing; Pod-Readme-v1.2.3/t/author-minimum-version.t0000644000175000017500000000033413366431456016551 0ustar rrrr#!perl BEGIN { unless ($ENV{AUTHOR_TESTING}) { print qq{1..0 # SKIP these tests are for testing by the author\n}; exit } } use Test::More; use Test::MinimumVersion; all_minimum_version_from_metayml_ok(); Pod-Readme-v1.2.3/t/author-portability.t0000644000175000017500000000047113366431456015757 0ustar rrrr BEGIN { unless ($ENV{AUTHOR_TESTING}) { print qq{1..0 # SKIP these tests are for testing by the author\n}; exit } } use strict; use warnings; use Test::More; eval 'use Test::Portability::Files'; plan skip_all => 'Test::Portability::Files required for testing portability' if $@; run_tests(); Pod-Readme-v1.2.3/t/release-check-manifest.t0000644000175000017500000000071013366431456016410 0ustar rrrr#!perl -T BEGIN { unless ($ENV{RELEASE_TESTING}) { print qq{1..0 # SKIP these tests are for release candidate testing\n}; exit } } BEGIN { unless ($ENV{RELEASE_TESTING}) { require Test::More; Test::More::plan(skip_all => 'these tests are for release candidate testing'); } } use Test::More; eval "use Test::CheckManifest 1.24"; plan skip_all => "Test::CheckManifest 1.24 required for testing MANIFEST" if $@; ok_manifest(); Pod-Readme-v1.2.3/t/author-clean-namespaces.t0000644000175000017500000000076713366431456016624 0ustar rrrr BEGIN { unless ($ENV{AUTHOR_TESTING}) { print qq{1..0 # SKIP these tests are for testing by the author\n}; exit } } use strict; use warnings; # this test was generated with Dist::Zilla::Plugin::Test::CleanNamespaces 0.006 use Test::More 0.94; use Test::CleanNamespaces 0.15; subtest all_namespaces_clean => sub { namespaces_clean( grep { my $mod = $_; not grep { $mod =~ $_ } qr/Pod::Readme::Types/ } Test::CleanNamespaces->find_modules ); }; done_testing; Pod-Readme-v1.2.3/t/data/0000775000175000017500000000000013366431456012641 5ustar rrrrPod-Readme-v1.2.3/t/data/README.txt0000644000175000017500000000021313366431456014331 0ustar rrrrNAME Test - this is a test DESCRIPTION This is a sample file for testing. Please ignore. A heading Nothing to see here. Pod-Readme-v1.2.3/t/data/README-1.pod0000644000175000017500000000022213366431456014432 0ustar rrrr=head1 NAME Test - this is a test =head1 DESCRIPTION This is a sample file for testing. Please ignore. =head2 A heading Nothing to see here. Pod-Readme-v1.2.3/t/data/META-1.yml0000644000175000017500000000201213366431456014241 0ustar rrrr--- abstract: 'generate README files from POD' author: - 'Robert Rothenberg ' build_requires: Exporter::Lite: 0 ExtUtils::MakeMaker: 6.59 Test::Most: 0 configure_requires: ExtUtils::MakeMaker: 6.59 distribution_type: module dynamic_config: 1 generated_by: 'Module::Install version 1.06' license: artistic2 meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: 1.4 name: Pod-Readme no_index: directory: - inc - t - xt requires: CPAN::Changes: 0 CPAN::Meta: 0 ExtUtils::MakeMaker: 6.56 File::Slurp: 0 Hash::Util: 0 IO: 0 Module::CoreList: 0 Moose: 0 MooseX::Object::Pluggable: 0 MooseX::Types::IO: 0 MooseX::Types::Path::Class: 0 Path::Class: 0 Try::Tiny: 0 namespace::autoclean: 0 perl: 5.10.1 version: 0.77 resources: bugtracker: https://rt.cpan.org/Public/Dist/Display.html?Name=Pod-Readme license: http://www.perlfoundation.org/artistic_license_2_0 repository: git://github.com/bigpresh/Pod-Readme.git version: 1.000000_001 Pod-Readme-v1.2.3/t/author-critic.t0000644000175000017500000000041713366431456014672 0ustar rrrr#!perl BEGIN { unless ($ENV{AUTHOR_TESTING}) { print qq{1..0 # SKIP these tests are for testing by the author\n}; exit } } use strict; use warnings; use Test::Perl::Critic (-profile => "t/etc/perlcritic.rc") x!! -e "t/etc/perlcritic.rc"; all_critic_ok(); Pod-Readme-v1.2.3/t/release-trailing-space.t0000644000175000017500000000115713366431456016437 0ustar rrrr#!perl BEGIN { unless ($ENV{RELEASE_TESTING}) { print qq{1..0 # SKIP these tests are for release candidate testing\n}; exit } } use strict; use warnings; use Test::More; eval "use Test::TrailingSpace"; if ($@) { plan skip_all => "Test::TrailingSpace required for trailing space test."; } else { plan tests => 1; } # TODO: add .pod, .PL, the README/Changes/TODO/etc. documents and possibly # some other stuff. my $finder = Test::TrailingSpace->new( { root => '.', filename_regex => qr#\.(?:p[lm])\z#, }, ); # TEST $finder->no_trailing_space( "No trailing space was found." ); Pod-Readme-v1.2.3/t/author-pod-syntax.t0000644000175000017500000000045413366431456015524 0ustar rrrr#!perl BEGIN { unless ($ENV{AUTHOR_TESTING}) { print qq{1..0 # SKIP these tests are for testing by the author\n}; exit } } # This file was automatically generated by Dist::Zilla::Plugin::PodSyntaxTests. use strict; use warnings; use Test::More; use Test::Pod 1.41; all_pod_files_ok(); Pod-Readme-v1.2.3/t/author-no-tabs.t0000644000175000017500000000244613366431456014764 0ustar rrrr BEGIN { unless ($ENV{AUTHOR_TESTING}) { print qq{1..0 # SKIP these tests are for testing by the author\n}; exit } } use strict; use warnings; # this test was generated with Dist::Zilla::Plugin::Test::NoTabs 0.15 use Test::More 0.88; use Test::NoTabs; my @files = ( 'bin/pod2readme', 'lib/Pod/Readme.pm', 'lib/Pod/Readme/Filter.pm', 'lib/Pod/Readme/Plugin.pm', 'lib/Pod/Readme/Plugin/changes.pm', 'lib/Pod/Readme/Plugin/requires.pm', 'lib/Pod/Readme/Plugin/version.pm', 'lib/Pod/Readme/Types.pm', 't/00-report-prereqs.dd', 't/00-report-prereqs.t', 't/10-pod-readme-filter.t', 't/20-pod-readme.t', 't/author-clean-namespaces.t', 't/author-critic.t', 't/author-eof.t', 't/author-eol.t', 't/author-minimum-version.t', 't/author-no-tabs.t', 't/author-pod-syntax.t', 't/author-portability.t', 't/data/META-1.yml', 't/data/README-1.pod', 't/data/README.txt', 't/lib/Pod/Readme/Plugin/noop.pm', 't/lib/Pod/Readme/Test.pm', 't/lib/Pod/Readme/Test/Kit.pm', 't/plugins/changes.t', 't/plugins/requires.t', 't/plugins/version.t', 't/release-check-manifest.t', 't/release-fixme.t', 't/release-kwalitee.t', 't/release-trailing-space.t' ); notabs_ok($_) foreach @files; done_testing; Pod-Readme-v1.2.3/t/plugins/0000775000175000017500000000000013366431456013411 5ustar rrrrPod-Readme-v1.2.3/t/plugins/version.t0000644000175000017500000000213313366431456015260 0ustar rrrruse strict; use warnings; use Test::More; use Test::Deep; use Test::Exception; use Cwd; use File::Compare qw/ compare_text /; use File::Temp qw/ tempfile /; use Path::Tiny qw/ path /; use lib 't/lib'; use Pod::Readme::Test; # use Pod::Readme::Test::Kit; our $VERSION = '1.23'; # for testing my $class = 'Pod::Readme'; use_ok $class; isa_ok $prf = $class->new( input_file => $0, output_fh => $io, ), $class; { filter_lines('=for readme plugin version', ''); is $out, "=head1 VERSION\n\n${VERSION}\n\n"; is_deeply [ $prf->depends_on ], [ $prf->version_file, $prf->input_file ], 'depends_on'; lives_ok { $prf->dependencies_updated } 'dependencies_updated'; reset_out(); $prf->version_run(0); } { filter_lines("=for readme plugin version file=${0} title='THIS VER'", ''); is $out, "=head1 THIS VER\n\n${VERSION}\n\n"; reset_out(); $prf->version_run(0); } { filter_lines('=for readme plugin version heading-level=2 title="Version"', ''); is $out, "=head2 Version\n\n${VERSION}\n\n"; reset_out(); $prf->version_run(0); } done_testing; Pod-Readme-v1.2.3/t/plugins/requires.t0000644000175000017500000000335513366431456015441 0ustar rrrruse strict; use warnings; use Test::More; use Test::Deep; use Test::Exception; use Cwd; use File::Compare qw/ compare_text /; use File::Temp qw/ tempfile /; use Path::Tiny qw/ path /; use lib 't/lib'; use Pod::Readme::Test; # use Pod::Readme::Test::Kit; my $class = 'Pod::Readme'; use_ok $class; isa_ok $prf = $class->new( input_file => $0, output_fh => $io, base_dir => cwd, ), $class; SKIP: { # Workaround a possible bug in Travis-CI's build system, where # running Makefile.PL no longer generates the META.yml file # because the inc dir is present, but it is not in author mode. skip "cannot find default META.yml", 3 unless -e path($prf->base_dir, 'META.yml') ; lives_ok { filter_lines( '=for readme plugin requires', '' ); } 'run requires plugin'; like $out, qr/=head1 REQUIREMENTS\n\n/, '=head1'; like $out, qr/\nThis distribution requires the following modules:\n\n/, 'description'; is_deeply [ $prf->depends_on ], [ $prf->requires_from_file, $prf->input_file ], 'depends_on'; lives_ok { $prf->dependencies_updated } 'dependencies_updated'; reset_out(); $prf->requires_run(0); } { filter_lines( '=for readme plugin requires from-file="t/data/META-1.yml" title="PREREQS"', '' ); note $out; like $out, qr/=head1 PREREQS\n\n/, '=head1'; like $out, qr/\nThis distribution requires Perl v5\.10\.1\.\n\n/, 'minimum perl'; # TODO: test content # - test no-omit-core option reset_out(); $prf->requires_run(0); } { dies_ok { filter_lines( '=for readme plugin requires file=nonexistent', '' ); } 'die on bad filename'; reset_out(); $prf->requires_run(0); } done_testing; Pod-Readme-v1.2.3/t/plugins/changes.t0000644000175000017500000000162013366431456015203 0ustar rrrruse strict; use warnings; use Test::More; use Test::Deep; use Test::Exception; use Cwd; use File::Compare qw/ compare_text /; use File::Temp qw/ tempfile /; use Path::Tiny qw/ path /; use lib 't/lib'; use Pod::Readme::Test; # use Pod::Readme::Test::Kit; my $class = 'Pod::Readme'; use_ok $class; isa_ok $prf = $class->new( input_file => $0, output_fh => $io, ), $class; { filter_lines( '=for readme plugin changes', '' ); is_deeply [ $prf->depends_on ], [ $prf->changes_file, $prf->input_file ], 'depends_on'; lives_ok { $prf->dependencies_updated } 'dependencies_updated'; note $out; like $out, qr/=head1 RECENT CHANGES\n\n/, '=head1'; # TODO: test content: # - Changes file with sections (using alternative file) # - Changes file without sections (using alternative file) # - verbatim mode # - changed title reset_out(); } done_testing; Pod-Readme-v1.2.3/t/20-pod-readme.t0000644000175000017500000000574513366431456014362 0ustar rrrruse strict; use warnings; use Test::More; use Test::Deep; use Test::Exception; use Cwd; use File::Compare qw/ compare_text /; use File::Temp qw/ tempfile /; use Path::Tiny qw/ path /; use Pod::Simple::Text; use lib 't/lib'; use Pod::Readme::Test; # use Pod::Readme::Test::Kit; my $class = 'Pod::Readme'; use_ok $class; isa_ok $prf = $class->new( output_fh => $io, ), $class; { ok !$prf->can('cmd_noop'), 'no noop'; filter_lines('=for readme plugin noop'); is $prf->mode, 'pod:for', 'mode'; filter_lines(''); is $prf->mode, 'pod', 'mode'; ok $prf->in_target, 'in target'; is $out, '', 'no output'; can_ok( $prf, 'cmd_noop' ); isa_ok( $prf, 'Pod::Readme::Filter' ); throws_ok { filter_lines('=for readme plugin noop::invalid'); is $prf->mode, 'pod:for', 'mode'; filter_lines(''); } qr/Unable to locate plugin 'noop::invalid'/, 'bad plugin'; is $prf->mode('pod'), 'pod', 'mode reset'; filter_lines( '=for readme plugin noop', '' ); can_ok( $prf, qw/ noop_bool noop_str / ); ok !$prf->noop_bool, 'plugin accessor default'; is $prf->noop_str, '', 'plugin accessor default'; filter_lines( '=for readme plugin noop bool', '' ); ok $prf->noop_bool, 'plugin accessor set'; filter_lines( '=for readme plugin noop no-bool str="Isn\'t this nice?"', '' ); ok !$prf->noop_bool, 'plugin accessor unset'; is $prf->noop_str, "Isn\'t this nice?", 'plugin accessor set'; throws_ok { filter_lines( '=for readme plugin noop no-bool bad-attr="this"', '' ); } qr/Invalid argument key 'bad-attr' at input line \d+/; }; { my $source = 't/data/README-1.pod'; lives_ok { my $dest = ( tempfile( UNLINK => 1 ) )[1]; note $dest; ok my $parser = Pod::Readme->new, 'new (no args)'; $parser->parse_from_file( $source, $dest ); ok !compare_text( $dest, 't/data/README.txt' ), 'expected output'; } 'parse_from_file'; lives_ok { my $dest = ( tempfile( UNLINK => 1 ) )[1]; note $dest; Pod::Readme->parse_from_file( $source, $dest ); ok !compare_text( $dest, 't/data/README.txt' ), 'expected output'; } 'parse_from_file (class method)'; lives_ok { open my $source_fh, '<', $source; my ( $dest_fh, $dest ) = tempfile( UNLINK => 1 ); note $dest; ok my $parser = Pod::Readme->new, 'new (no args)'; $parser->parse_from_filehandle( $source_fh, $dest_fh ); ok !compare_text( $dest, 't/data/README.txt' ), 'expected output'; close $source_fh; } 'parse_from_filehandle'; lives_ok { open my $source_fh, '<', $source; my ( $dest_fh, $dest ) = tempfile( UNLINK => 1 ); note $dest; Pod::Readme->parse_from_filehandle( $source_fh, $dest_fh ); ok !compare_text( $dest, 't/data/README.txt' ), 'expected output'; close $source_fh; } 'parse_from_filehandle (class method)'; } done_testing; Pod-Readme-v1.2.3/t/00-report-prereqs.t0000644000175000017500000001345213366431456015327 0ustar rrrr#!perl use strict; use warnings; # This test was generated by Dist::Zilla::Plugin::Test::ReportPrereqs 0.027 use Test::More tests => 1; use Module::Metadata; use File::Spec; # from $version::LAX my $lax_version_re = qr/(?: undef | (?: (?:[0-9]+) (?: \. | (?:\.[0-9]+) (?:_[0-9]+)? )? | (?:\.[0-9]+) (?:_[0-9]+)? ) | (?: v (?:[0-9]+) (?: (?:\.[0-9]+)+ (?:_[0-9]+)? )? | (?:[0-9]+)? (?:\.[0-9]+){2,} (?:_[0-9]+)? ) )/x; # hide optional CPAN::Meta modules from prereq scanner # and check if they are available my $cpan_meta = "CPAN::Meta"; my $cpan_meta_pre = "CPAN::Meta::Prereqs"; my $HAS_CPAN_META = eval "require $cpan_meta; $cpan_meta->VERSION('2.120900')" && eval "require $cpan_meta_pre"; ## no critic # Verify requirements? my $DO_VERIFY_PREREQS = 1; sub _max { my $max = shift; $max = ( $_ > $max ) ? $_ : $max for @_; return $max; } sub _merge_prereqs { my ($collector, $prereqs) = @_; # CPAN::Meta::Prereqs object if (ref $collector eq $cpan_meta_pre) { return $collector->with_merged_prereqs( CPAN::Meta::Prereqs->new( $prereqs ) ); } # Raw hashrefs for my $phase ( keys %$prereqs ) { for my $type ( keys %{ $prereqs->{$phase} } ) { for my $module ( keys %{ $prereqs->{$phase}{$type} } ) { $collector->{$phase}{$type}{$module} = $prereqs->{$phase}{$type}{$module}; } } } return $collector; } my @include = qw( ); my @exclude = qw( ); # Add static prereqs to the included modules list my $static_prereqs = do './t/00-report-prereqs.dd'; # Merge all prereqs (either with ::Prereqs or a hashref) my $full_prereqs = _merge_prereqs( ( $HAS_CPAN_META ? $cpan_meta_pre->new : {} ), $static_prereqs ); # Add dynamic prereqs to the included modules list (if we can) my ($source) = grep { -f } 'MYMETA.json', 'MYMETA.yml'; my $cpan_meta_error; if ( $source && $HAS_CPAN_META && (my $meta = eval { CPAN::Meta->load_file($source) } ) ) { $full_prereqs = _merge_prereqs($full_prereqs, $meta->prereqs); } else { $cpan_meta_error = $@; # capture error from CPAN::Meta->load_file($source) $source = 'static metadata'; } my @full_reports; my @dep_errors; my $req_hash = $HAS_CPAN_META ? $full_prereqs->as_string_hash : $full_prereqs; # Add static includes into a fake section for my $mod (@include) { $req_hash->{other}{modules}{$mod} = 0; } for my $phase ( qw(configure build test runtime develop other) ) { next unless $req_hash->{$phase}; next if ($phase eq 'develop' and not $ENV{AUTHOR_TESTING}); for my $type ( qw(requires recommends suggests conflicts modules) ) { next unless $req_hash->{$phase}{$type}; my $title = ucfirst($phase).' '.ucfirst($type); my @reports = [qw/Module Want Have/]; for my $mod ( sort keys %{ $req_hash->{$phase}{$type} } ) { next if $mod eq 'perl'; next if grep { $_ eq $mod } @exclude; my $file = $mod; $file =~ s{::}{/}g; $file .= ".pm"; my ($prefix) = grep { -e File::Spec->catfile($_, $file) } @INC; my $want = $req_hash->{$phase}{$type}{$mod}; $want = "undef" unless defined $want; $want = "any" if !$want && $want == 0; my $req_string = $want eq 'any' ? 'any version required' : "version '$want' required"; if ($prefix) { my $have = Module::Metadata->new_from_file( File::Spec->catfile($prefix, $file) )->version; $have = "undef" unless defined $have; push @reports, [$mod, $want, $have]; if ( $DO_VERIFY_PREREQS && $HAS_CPAN_META && $type eq 'requires' ) { if ( $have !~ /\A$lax_version_re\z/ ) { push @dep_errors, "$mod version '$have' cannot be parsed ($req_string)"; } elsif ( ! $full_prereqs->requirements_for( $phase, $type )->accepts_module( $mod => $have ) ) { push @dep_errors, "$mod version '$have' is not in required range '$want'"; } } } else { push @reports, [$mod, $want, "missing"]; if ( $DO_VERIFY_PREREQS && $type eq 'requires' ) { push @dep_errors, "$mod is not installed ($req_string)"; } } } if ( @reports ) { push @full_reports, "=== $title ===\n\n"; my $ml = _max( map { length $_->[0] } @reports ); my $wl = _max( map { length $_->[1] } @reports ); my $hl = _max( map { length $_->[2] } @reports ); if ($type eq 'modules') { splice @reports, 1, 0, ["-" x $ml, "", "-" x $hl]; push @full_reports, map { sprintf(" %*s %*s\n", -$ml, $_->[0], $hl, $_->[2]) } @reports; } else { splice @reports, 1, 0, ["-" x $ml, "-" x $wl, "-" x $hl]; push @full_reports, map { sprintf(" %*s %*s %*s\n", -$ml, $_->[0], $wl, $_->[1], $hl, $_->[2]) } @reports; } push @full_reports, "\n"; } } } if ( @full_reports ) { diag "\nVersions for all modules listed in $source (including optional ones):\n\n", @full_reports; } if ( $cpan_meta_error || @dep_errors ) { diag "\n*** WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING ***\n"; } if ( $cpan_meta_error ) { my ($orig_source) = grep { -f } 'MYMETA.json', 'MYMETA.yml'; diag "\nCPAN::Meta->load_file('$orig_source') failed with: $cpan_meta_error\n"; } if ( @dep_errors ) { diag join("\n", "\nThe following REQUIRED prerequisites were not satisfied:\n", @dep_errors, "\n" ); } pass; # vim: ts=4 sts=4 sw=4 et: Pod-Readme-v1.2.3/t/release-fixme.t0000644000175000017500000000040513366431456014640 0ustar rrrr#!perl BEGIN { unless ($ENV{RELEASE_TESTING}) { print qq{1..0 # SKIP these tests are for release candidate testing\n}; exit } } # This test is generated by Dist::Zilla::Plugin::Test::Fixme use strict; use warnings; use Test::Fixme; run_tests(); Pod-Readme-v1.2.3/t/author-eol.t0000644000175000017500000000250013366431456014167 0ustar rrrr BEGIN { unless ($ENV{AUTHOR_TESTING}) { print qq{1..0 # SKIP these tests are for testing by the author\n}; exit } } use strict; use warnings; # this test was generated with Dist::Zilla::Plugin::Test::EOL 0.19 use Test::More 0.88; use Test::EOL; my @files = ( 'bin/pod2readme', 'lib/Pod/Readme.pm', 'lib/Pod/Readme/Filter.pm', 'lib/Pod/Readme/Plugin.pm', 'lib/Pod/Readme/Plugin/changes.pm', 'lib/Pod/Readme/Plugin/requires.pm', 'lib/Pod/Readme/Plugin/version.pm', 'lib/Pod/Readme/Types.pm', 't/00-report-prereqs.dd', 't/00-report-prereqs.t', 't/10-pod-readme-filter.t', 't/20-pod-readme.t', 't/author-clean-namespaces.t', 't/author-critic.t', 't/author-eof.t', 't/author-eol.t', 't/author-minimum-version.t', 't/author-no-tabs.t', 't/author-pod-syntax.t', 't/author-portability.t', 't/data/META-1.yml', 't/data/README-1.pod', 't/data/README.txt', 't/lib/Pod/Readme/Plugin/noop.pm', 't/lib/Pod/Readme/Test.pm', 't/lib/Pod/Readme/Test/Kit.pm', 't/plugins/changes.t', 't/plugins/requires.t', 't/plugins/version.t', 't/release-check-manifest.t', 't/release-fixme.t', 't/release-kwalitee.t', 't/release-trailing-space.t' ); eol_unix_ok($_, { trailing_whitespace => 1 }) foreach @files; done_testing; Pod-Readme-v1.2.3/t/10-pod-readme-filter.t0000644000175000017500000001114613366431456015634 0ustar rrrruse strict; use warnings; use Test::More; use Test::Deep; use Test::Exception; use Cwd; use File::Compare qw/ compare_text /; use File::Temp qw/ tempfile /; use Path::Tiny qw/ path /; use lib 't/lib'; use Pod::Readme::Test; # use Pod::Readme::Test::Kit; my $class = 'Pod::Readme::Filter'; use_ok $class; isa_ok $prf = $class->new( output_fh => $io, ), 'Pod::Readme::Filter'; { can_ok( $prf, "cmd_" . $_ ) for qw/ stop start continue plugin /; ok $prf->in_target, 'default in target'; is $prf->mode, 'default', 'mode'; is $prf->base_dir->stringify, '.', 'base_dir'; } { ok !$prf->cmd_stop, 'cmd_stop'; ok !$prf->in_target, 'not in target'; ok $prf->cmd_start, 'cmd_start'; ok $prf->in_target, 'in target'; ok !$prf->cmd_stop, 'cmd_stop'; ok !$prf->in_target, 'not in target'; ok $prf->cmd_continue, 'cmd_continue'; ok $prf->in_target, 'in target'; }; { filter_lines('=pod'); is $out, "=pod\n", 'expected output'; is $prf->mode, 'pod', 'mode'; ok $prf->in_target, 'in target'; reset_out(); }; { filter_lines('=for readme stop'); is $prf->mode, 'pod:for', 'mode'; filter_lines(''); is $prf->mode, 'pod', 'mode'; is $out, '', 'no output'; ok !$prf->in_target, 'not in target'; filter_lines( 'This should not be copied.', '', 'Boop!', '' ); is $out, '', 'no output'; filter_lines('=for readme continue'); is $prf->mode, 'pod:for', 'mode'; filter_lines(''); is $prf->mode, 'pod', 'mode'; ok $prf->in_target, 'in target'; is $out, '', 'no output'; }; { filter_lines('=for readme stop'); is $prf->mode, 'pod:for', 'mode'; filter_lines(''); is $prf->mode, 'pod', 'mode'; is $out, '', 'no output'; ok !$prf->in_target, 'not in target'; filter_lines( 'This should not be copied.', '', 'Boop!', '' ); is $out, '', 'no output'; filter_lines('=for readme start'); is $prf->mode, 'pod:for', 'mode'; filter_lines(''); is $prf->mode, 'pod', 'mode'; ok $prf->in_target, 'in target'; is $out, '', 'no output'; }; { throws_ok { filter_lines('=for readme plugin noop::invalid'); is $prf->mode, 'pod:for', 'mode'; filter_lines(''); } qr/Unable to locate plugin 'noop::invalid'/, 'bad plugin'; is $prf->mode('pod'), 'pod', 'mode reset'; }; { filter_lines('=cut'); is $prf->mode, 'default', 'default mode'; filter_lines(''); is $out, '', 'no content'; filter_lines('=head1 TEST'); is $prf->mode, 'pod', 'pod mode'; filter_lines(''); is $out, "=head1 TEST\n\n", 'expected content'; reset_out(); }; { filter_lines( "This should be copied.", '' ); is $out, "This should be copied.\n\n", 'output'; reset_out(); }; { filter_lines('=begin text'); is $prf->mode, 'target:text', 'mode'; filter_lines( '', 'Something', '', '=end text', '' ); is $out, '', 'no content'; reset_out(); } { filter_lines('=begin readme'); is $prf->mode, 'pod:begin', 'mode'; filter_lines( '', 'Something', '', '=end readme', '' ); like $out, qr/^Something\n/, 'expected content (minimal)'; TODO: { local $TODO = 'extra newline'; is $out, "Something\n", 'expected content'; } reset_out(); } { filter_lines('=begin readme text'); is $prf->mode, 'pod:begin', 'mode'; filter_lines( '', 'Something', '', '=end readme', '' ); TODO: { is $out, "=begin text\n\nSomething\n\n=end text\n\n", 'expected content'; } reset_out(); } { filter_lines('=begin :readme'); is $prf->mode, 'pod:begin', 'mode'; filter_lines( '', 'Something', '', '=end :readme', '' ); like $out, qr/^Something\n/, 'expected content (minimal)'; TODO: { local $TODO = 'extra newline'; is $out, "Something\n", 'expected content'; } reset_out(); } { can_ok $prf, qw/ parse_cmd_args /; lives_ok { my $res = $prf->parse_cmd_args( undef, 'arg1', 'no-arg2', 'arg3="This is a string"', 'arg4=value', ); note( explain $res); is_deeply $res, { 'arg1' => 1, 'arg2' => 0, 'arg3' => 'This is a string', 'arg4' => 'value' }, 'expected parsing of arguments list'; } 'parse_cmd_args'; throws_ok { my $res = $prf->parse_cmd_args( [qw/ arg1 arg2 arg3 /], 'arg1', 'no-arg2', 'arg3="This is a string"', 'arg4=value', ); } qr/Invalid argument key 'arg4'/, 'bad arguments'; } { can_ok $prf, qw/ depends_on /; is_deeply [ $prf->depends_on ], [], 'depends_on'; } done_testing; Pod-Readme-v1.2.3/t/lib/0000775000175000017500000000000013366431456012476 5ustar rrrrPod-Readme-v1.2.3/t/lib/Pod/0000775000175000017500000000000013366431456013220 5ustar rrrrPod-Readme-v1.2.3/t/lib/Pod/Readme/0000775000175000017500000000000013366431456014415 5ustar rrrrPod-Readme-v1.2.3/t/lib/Pod/Readme/Test/0000775000175000017500000000000013366431456015334 5ustar rrrrPod-Readme-v1.2.3/t/lib/Pod/Readme/Test/Kit.pm0000644000175000017500000000054213366431456016420 0ustar rrrrpackage Pod::Readme::Test::Kit; use Test::Kit; include 'strict'; include 'warnings'; include 'Test::More'; include 'Test::Deep'; include 'Test::Exception'; include 'Cwd'; include 'File::Temp' => { import => [qw/ tempfile /], }; include 'File::Compare' => { import => [qw/ compare_text /], }; include 'Path::Tiny'; include 'Pod::Readme::Test'; 1; Pod-Readme-v1.2.3/t/lib/Pod/Readme/Test.pm0000644000175000017500000000075013366431456015672 0ustar rrrrpackage Pod::Readme::Test; use Exporter qw/ import /; use IO::String; require Test::More; our $out; our $io = IO::String->new($out); our $prf; our @EXPORT = qw/ $prf $out $io filter_lines reset_out /; our @EXPORT_OK = @EXPORT; sub filter_lines { my @lines = @_; foreach my $line (@lines) { Test::More::note $line if $line =~ /^=(?:\w+)/; $prf->filter_line( $line . "\n" ); } } sub reset_out { $io->close; $out = ''; $io->open($out); } 1; Pod-Readme-v1.2.3/t/lib/Pod/Readme/Plugin/0000775000175000017500000000000013366431456015653 5ustar rrrrPod-Readme-v1.2.3/t/lib/Pod/Readme/Plugin/noop.pm0000644000175000017500000000150513366431456017163 0ustar rrrrpackage Pod::Readme::Plugin::noop; use Moo::Role; use Types::Standard qw/ Bool Str /; =head1 NAME Pod::Readme::Plugin::noop - do nothing =head1 SYNOPSIS =pod =for readme plugin noop =head1 DESCRIPTION This is a no-op plugin. =cut requires 'parse_cmd_args'; has noop_bool => ( is => 'rw', isa => Bool, lazy => 1, default => 0, ); has noop_str => ( is => 'rw', isa => Str, lazy => 1, default => '', ); sub cmd_noop { my ( $self, @args ) = @_; my $res = $self->parse_cmd_args( [qw/ bool str /], @args ); foreach my $key ( keys %{$res} ) { if ( my $method = $self->can("noop_${key}") ) { $self->$method( $res->{$key} ); } else { die "Invalid key: '${key}'"; } } } use namespace::autoclean; 1; Pod-Readme-v1.2.3/t/00-report-prereqs.dd0000644000175000017500000000723313366431456015453 0ustar rrrrdo { my $x = { 'develop' => { 'requires' => { 'Test::CleanNamespaces' => '0.15', 'Test::EOF' => '0', 'Test::EOL' => '0', 'Test::Kwalitee' => '1.21', 'Test::MinimumVersion' => '0', 'Test::More' => '0.88', 'Test::NoTabs' => '0', 'Test::Perl::Critic' => '0', 'Test::Pod' => '1.41', 'Test::Portability::Files' => '0', 'Test::TrailingSpace' => '0.0203' } }, 'runtime' => { 'recommends' => { 'Pod::Man' => '0', 'Pod::Markdown' => '0', 'Pod::Markdown::Github' => '0', 'Pod::Simple::HTML' => '0', 'Pod::Simple::LaTeX' => '0', 'Pod::Simple::RTF' => '0', 'Pod::Simple::Text' => '0', 'Pod::Simple::XHTML' => '0', 'Type::Tiny::XS' => '0' }, 'requires' => { 'CPAN::Changes' => '0.30', 'CPAN::Meta' => '0', 'Class::Method::Modifiers' => '0', 'File::Slurp' => '0', 'Getopt::Long::Descriptive' => '0', 'Hash::Util' => '0', 'List::Util' => '1.33', 'Module::CoreList' => '0', 'Moo' => '0', 'Moo::Role' => '0', 'MooX::HandlesVia' => '0', 'Path::Tiny' => '0', 'Pod::Simple' => '0', 'Role::Tiny' => '0', 'Scalar::Util' => '0', 'Try::Tiny' => '0', 'Type::Tiny' => '1.000000', 'Types::Standard' => '0', 'namespace::autoclean' => '0', 'perl' => 'v5.10.1' } }, 'test' => { 'recommends' => { 'CPAN::Meta' => '2.120900' }, 'requires' => { 'Cwd' => '0', 'File::Compare' => '0', 'File::Spec' => '0', 'IO::String' => '0', 'Module::Metadata' => '0', 'Pod::Simple::Text' => '0', 'Test::Deep' => '0', 'Test::Exception' => '0', 'Test::Kit' => '0', 'Test::More' => '0' } } }; $x; }Pod-Readme-v1.2.3/t/author-eof.t0000644000175000017500000000064113366431456014165 0ustar rrrr BEGIN { unless ($ENV{AUTHOR_TESTING}) { print qq{1..0 # SKIP these tests are for testing by the author\n}; exit } } use strict; use warnings; use Test::More; # Generated by Dist::Zilla::Plugin::Test::EOF 0.0501 eval "use Test::EOF"; plan skip_all => 'Test::EOF required to test for correct end of file flag' if $@; all_perl_files_ok({ minimum_newlines => 1, maximum_newlines => 4 }); done_testing(); Pod-Readme-v1.2.3/README.pod0000644000175000017500000000575613366431456013141 0ustar rrrr=head1 NAME Pod::Readme - Intelligently generate a README file from POD =head1 VERSION v1.2.0 =head1 SYNOPSIS In a module's POD: =head1 NAME MyApp - my nifty app =for readme plugin version =head1 DESCRIPTION This is a nifty app. =begin :readme =for readme plugin requires =head1 INSTALLATION ... =end :readme =for readme stop =head1 METHODS ... Then from the command-line: pod2readme lib/MyModule.pm README =head1 DESCRIPTION This module filters POD to generate a F file, by using POD commands to specify which parts are included or excluded from the F file. See the L documentation for more details on the POD syntax that this module recognizes. See L for command-line usage. =head1 INSTALLATION See L. =head2 Required Modules This distribution requires Perl v5.10.1. This distribution requires the following modules: =over 4 =item * L =item * L (version 0.30) =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =back =head1 RECENT CHANGES =head2 Bug Fixes =over 4 =item * Specify minimum version of List::Util, GH#22. =back =head2 Enhancements =over 4 =item * Added "md" as an alias for "markdown" in pod2readme. =back =head2 Incompatabilities =over 4 =item * Removed DistZilla type from Pod::Readme::Types, as it was not necessary. =back =head2 Toolchain =over 4 =item * Remove use of Module::Install, fixes GH#21. =item * Use Dist::Zilla to build the distribution. =back See the F file for a longer revision history. =head1 CAVEATS This module is intended to be used by module authors for their own modules. It is not recommended for generating F files from arbitrary Perl modules from untrusted sources. =head1 SEE ALSO See L, L and L. =head1 AUTHORS The original version was by Robert Rothenberg until 2010, when maintenance was taken over by David Precious . In 2014, Robert Rothenberg rewrote the module to use filtering instead of subclassing a POD parser. =head2 Acknowledgements Thanks to people who gave feedback and suggestions to posts about the rewrite of this module on L. =head2 Suggestions, Bug Reporting and Contributing This module is developed on GitHub at L =head1 LICENSE Copyright (c) 2005-2014 Robert Rothenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Pod-Readme-v1.2.3/META.json0000644000175000017500000001066713366431456013116 0ustar rrrr{ "abstract" : "Intelligently generate a README file from POD", "author" : [ "Robert Rothenberg " ], "dynamic_config" : 0, "generated_by" : "Dist::Zilla version 6.012, CPAN::Meta::Converter version 2.150010", "keywords" : [ "Moo", "data-driven", "development", "testing" ], "license" : [ "perl_5" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : 2 }, "name" : "Pod-Readme", "prereqs" : { "develop" : { "requires" : { "Test::CleanNamespaces" : "0.15", "Test::EOF" : "0", "Test::EOL" : "0", "Test::Kwalitee" : "1.21", "Test::MinimumVersion" : "0", "Test::More" : "0.88", "Test::NoTabs" : "0", "Test::Perl::Critic" : "0", "Test::Pod" : "1.41", "Test::Portability::Files" : "0", "Test::TrailingSpace" : "0.0203" } }, "runtime" : { "recommends" : { "Pod::Man" : "0", "Pod::Markdown" : "0", "Pod::Markdown::Github" : "0", "Pod::Simple::HTML" : "0", "Pod::Simple::LaTeX" : "0", "Pod::Simple::RTF" : "0", "Pod::Simple::Text" : "0", "Pod::Simple::XHTML" : "0", "Type::Tiny::XS" : "0" }, "requires" : { "CPAN::Changes" : "0.30", "CPAN::Meta" : "0", "Class::Method::Modifiers" : "0", "File::Slurp" : "0", "Getopt::Long::Descriptive" : "0", "Hash::Util" : "0", "List::Util" : "1.33", "Module::CoreList" : "0", "Moo" : "0", "Moo::Role" : "0", "MooX::HandlesVia" : "0", "Path::Tiny" : "0", "Pod::Simple" : "0", "Role::Tiny" : "0", "Scalar::Util" : "0", "Try::Tiny" : "0", "Type::Tiny" : "1.000000", "Types::Standard" : "0", "namespace::autoclean" : "0", "perl" : "v5.10.1" } }, "test" : { "recommends" : { "CPAN::Meta" : "2.120900" }, "requires" : { "Cwd" : "0", "File::Compare" : "0", "File::Spec" : "0", "IO::String" : "0", "Module::Metadata" : "0", "Pod::Simple::Text" : "0", "Test::Deep" : "0", "Test::Exception" : "0", "Test::Kit" : "0", "Test::More" : "0" } } }, "provides" : { "Pod::Readme" : { "file" : "lib/Pod/Readme.pm", "version" : "v1.2.3" }, "Pod::Readme::Filter" : { "file" : "lib/Pod/Readme/Filter.pm", "version" : "v1.2.3" }, "Pod::Readme::Plugin" : { "file" : "lib/Pod/Readme/Plugin.pm", "version" : "v1.2.3" }, "Pod::Readme::Plugin::changes" : { "file" : "lib/Pod/Readme/Plugin/changes.pm", "version" : "v1.2.3" }, "Pod::Readme::Plugin::requires" : { "file" : "lib/Pod/Readme/Plugin/requires.pm", "version" : "v1.2.3" }, "Pod::Readme::Plugin::version" : { "file" : "lib/Pod/Readme/Plugin/version.pm", "version" : "v1.2.3" }, "Pod::Readme::Types" : { "file" : "lib/Pod/Readme/Types.pm", "version" : "v1.2.3" } }, "release_status" : "stable", "resources" : { "bugtracker" : { "web" : "https://github.com/bigpresh/Pod-Readme/issues" }, "homepage" : "http://search.cpan.org/dist/Pod-Readme", "repository" : { "type" : "git", "url" : "git://github.com/bigpresh/Pod-Readme.git", "web" : "https://github.com/bigpresh/Pod-Readme" } }, "version" : "v1.2.3", "x_authority" : "cpan:RRWO", "x_contributors" : [ "David A. Desrosiers ", "David Precious ", "Ivan Bessarabov ", "Karen Etheridge ", "Karl Williamson ", "Lucas Kanashiro ", "Mohammad S Anwar ", "Sergey Romanov ", "Yanick Champoux " ], "x_generated_by_perl" : "v5.26.1", "x_serialization_backend" : "Cpanel::JSON::XS version 3.0239" } Pod-Readme-v1.2.3/MANIFEST.SKIP0000644000175000017500000000216513366431456013365 0ustar rrrr.*~$ .*\.(bak|old|tmp)$ \.git/.* \.gitignore # Begin standard Module::Manifest::Skip list: # ExtUtils::MakeMaker ^blib/ ^blibdirs$ ^blibdirs\.ts$ ^bpm_to_blib\.ts$ ^Makefile$ ^Makefile\.old$ ^MakeMaker-\d ^MANIFEST\.bak$ # ^MANIFEST\.SKIP$ ^MYMETA\. ^pm_to_blib$ ^pod2htm.* # Module::Build ^Build$ ^_build/ ^Build.bat$ ^Build.COM$ ^BUILD.COM$ ^build.com$ # Revision Control \bCVS\b \b.cvsignore\b \b_darcs\b \B\.git\b \B\.gitignore\b \B\.gitmodules\b \B\.hg\b \B\.hgignore\b \B\.hgtags\b \bRCS\b \bSCCS\b \B\.svn\b ,v$ ,B$ ,D$ \baegis.log$ # Author Extras ^inc/.*\.pod$ ^pkg/ # ^xt/ # ^dist.ini$ # Editors ~$ \#$ \b\.# \.kpf$ \.sw[pmno]$ ^\.vimrc$ # OS X \.DS_Store$ ^\.Trash/ \B\._ # VMS \bDescrip.MMS$ \bDESCRIP.MMS$ \bdescrip.mms$ # Development ^benchmarks/ ^core$ ^cover_db\b ^covered\b ^debian/ ^devel\. ^.devel-local$ ^out$ ^tmon.out$ ^old/ ^Old/ # Author Notes ^notes ^todo ^ToDo$ # Common Junk Files \.bak$ \.diff$ ^foo\b.* \.old$ \.orig$ \.patch$ \.rej$ \.tdy$ \.tmp$ ^\w$ \.ttc$ \.pmc$ # Added by Dist::Zilla::Plugin::Generate::ManifestSkip \.build/ Pod-Readme-.*/ Pod-Readme-.*\.tar\.gz \.mailmap$ cpanfile\.snapshot$ Pod-Readme-v1.2.3/LICENSE0000644000175000017500000004367413366431456012506 0ustar rrrrThis software is copyright (c) 2018 by Robert Rothenberg. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Terms of the Perl programming language system itself a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" --- The GNU General Public License, Version 1, February 1989 --- This software is Copyright (c) 2018 by Robert Rothenberg. This is free software, licensed under: The GNU General Public License, Version 1, February 1989 GNU GENERAL PUBLIC LICENSE Version 1, February 1989 Copyright (C) 1989 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The license agreements of most software companies try to keep users at the mercy of those companies. By contrast, our General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. The General Public License applies to the Free Software Foundation's software and to any other program whose authors commit to using it. You can use it for your programs, too. When we speak of free software, we are referring to freedom, not price. Specifically, the General Public License is designed to make sure that you have the freedom to give away or sell copies of free software, that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. For example, if you distribute copies of a such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. The precise terms and conditions for copying, distribution and modification follow. GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License Agreement applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any work containing the Program or a portion of it, either verbatim or with modifications. Each licensee is addressed as "you". 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this General Public License and to the absence of any warranty; and give any other recipients of the Program a copy of this General Public License along with the Program. You may charge a fee for the physical act of transferring a copy. 2. You may modify your copy or copies of the Program or any portion of it, and copy and distribute such modifications under the terms of Paragraph 1 above, provided that you also do the following: a) cause the modified files to carry prominent notices stating that you changed the files and the date of any change; and b) cause the whole of any work that you distribute or publish, that in whole or in part contains the Program or any part thereof, either with or without modifications, to be licensed at no charge to all third parties under the terms of this General Public License (except that you may choose to grant warranty protection to some or all third parties, at your option). c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the simplest and most usual way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this General Public License. d) You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. Mere aggregation of another independent work with the Program (or its derivative) on a volume of a storage or distribution medium does not bring the other work under the scope of these terms. 3. You may copy and distribute the Program (or a portion or derivative of it, under Paragraph 2) in object code or executable form under the terms of Paragraphs 1 and 2 above provided that you also do one of the following: a) accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Paragraphs 1 and 2 above; or, b) accompany it with a written offer, valid for at least three years, to give any third party free (except for a nominal charge for the cost of distribution) a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Paragraphs 1 and 2 above; or, c) accompany it with the information you received as to where the corresponding source code may be obtained. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form alone.) Source code for a work means the preferred form of the work for making modifications to it. For an executable file, complete source code means all the source code for all modules it contains; but, as a special exception, it need not include source code for modules which are standard libraries that accompany the operating system on which the executable file runs, or for standard header files or definitions files that accompany that operating system. 4. You may not copy, modify, sublicense, distribute or transfer the Program except as expressly provided under this General Public License. Any attempt otherwise to copy, modify, sublicense, distribute or transfer the Program is void, and will automatically terminate your rights to use the Program under this License. However, parties who have received copies, or rights to use copies, from you under this General Public License will not have their licenses terminated so long as such parties remain in full compliance. 5. By copying, distributing or modifying the Program (or any work based on the Program) you indicate your acceptance of this license to do so, and all its terms and conditions. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. 7. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of the license which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the license, you may choose any version ever published by the Free Software Foundation. 8. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS Appendix: How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to humanity, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) 19yy This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA Also add information on how to contact you by electronic and paper mail. If the program is interactive, make it output a short notice like this when it starts in an interactive mode: Gnomovision version 69, Copyright (C) 19xx name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (a program to direct compilers to make passes at assemblers) written by James Hacker. , 1 April 1989 Ty Coon, President of Vice That's all there is to it! --- The Artistic License 1.0 --- This software is Copyright (c) 2018 by Robert Rothenberg. This is free software, licensed under: The Artistic License 1.0 The Artistic License Preamble The intent of this document is to state the conditions under which a Package may be copied, such that the Copyright Holder maintains some semblance of artistic control over the development of the package, while giving the users of the package the right to use and distribute the Package in a more-or-less customary fashion, plus the right to make reasonable modifications. Definitions: - "Package" refers to the collection of files distributed by the Copyright Holder, and derivatives of that collection of files created through textual modification. - "Standard Version" refers to such a Package if it has not been modified, or has been modified in accordance with the wishes of the Copyright Holder. - "Copyright Holder" is whoever is named in the copyright or copyrights for the package. - "You" is you, if you're thinking about copying or distributing this Package. - "Reasonable copying fee" is whatever you can justify on the basis of media cost, duplication charges, time of people involved, and so on. (You will not be required to justify it to the Copyright Holder, but only to the computing community at large as a market that must bear the fee.) - "Freely Available" means that no fee is charged for the item itself, though there may be fees involved in handling the item. It also means that recipients of the item may redistribute it under the same conditions they received it. 1. You may make and give away verbatim copies of the source form of the Standard Version of this Package without restriction, provided that you duplicate all of the original copyright notices and associated disclaimers. 2. You may apply bug fixes, portability fixes and other modifications derived from the Public Domain or from the Copyright Holder. A Package modified in such a way shall still be considered the Standard Version. 3. You may otherwise modify your copy of this Package in any way, provided that you insert a prominent notice in each changed file stating how and when you changed that file, and provided that you do at least ONE of the following: a) place your modifications in the Public Domain or otherwise make them Freely Available, such as by posting said modifications to Usenet or an equivalent medium, or placing the modifications on a major archive site such as ftp.uu.net, or by allowing the Copyright Holder to include your modifications in the Standard Version of the Package. b) use the modified Package only within your corporation or organization. c) rename any non-standard executables so the names do not conflict with standard executables, which must also be provided, and provide a separate manual page for each non-standard executable that clearly documents how it differs from the Standard Version. d) make other distribution arrangements with the Copyright Holder. 4. You may distribute the programs of this Package in object code or executable form, provided that you do at least ONE of the following: a) distribute a Standard Version of the executables and library files, together with instructions (in the manual page or equivalent) on where to get the Standard Version. b) accompany the distribution with the machine-readable source of the Package with your modifications. c) accompany any non-standard executables with their corresponding Standard Version executables, giving the non-standard executables non-standard names, and clearly documenting the differences in manual pages (or equivalent), together with instructions on where to get the Standard Version. d) make other distribution arrangements with the Copyright Holder. 5. You may charge a reasonable copying fee for any distribution of this Package. You may charge any fee you choose for support of this Package. You may not charge a fee for this Package itself. However, you may distribute this Package in aggregate with other (possibly commercial) programs as part of a larger (possibly commercial) software distribution provided that you do not advertise this Package as a product of your own. 6. The scripts and library files supplied as input to or produced as output from the programs of this Package do not automatically fall under the copyright of this Package, but belong to whomever generated them, and may be sold commercially, and may be aggregated with this Package. 7. C or perl subroutines supplied by you and linked into this Package shall not be considered part of this Package. 8. The name of the Copyright Holder may not be used to endorse or promote products derived from this software without specific prior written permission. 9. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. The End Pod-Readme-v1.2.3/lib/0000775000175000017500000000000013366431456012233 5ustar rrrrPod-Readme-v1.2.3/lib/Pod/0000775000175000017500000000000013366431456012755 5ustar rrrrPod-Readme-v1.2.3/lib/Pod/Readme/0000775000175000017500000000000013366431456014152 5ustar rrrrPod-Readme-v1.2.3/lib/Pod/Readme/Plugin.pm0000644000175000017500000001605013366431456015746 0ustar rrrrpackage Pod::Readme::Plugin; use v5.10.1; use Moo::Role; our $VERSION = 'v1.2.3'; use Class::Method::Modifiers qw/ fresh /; use Hash::Util qw/ lock_keys /; use Try::Tiny; use Pod::Readme::Types qw/ Indentation /; =head1 NAME Pod::Readme::Plugin - Plugin role for Pod::Readme =head1 DESCRIPTION L v1.0 and later supports plugins that extend the capabilities of the module. =head1 WRITING PLUGINS Writing plugins is straightforward. Plugins are L modules in the C namespace. For example, package Pod::Readme::Plugin::myplugin; use Moo::Role; sub cmd_myplugin { my ($self, @args) = @_; my $res = $self->parse_cmd_args( [qw/ arg1 arg2 /], @args ); ... } When L encounters POD with =for readme plugin myplugin arg1 arg2 the plugin role will be loaded, and the C method will be run. Note that you do not need to specify a C method. Any method prefixed with "cmd_" will be a command that can be called using the C<=for readme command> syntax. A plugin parses arguments using the L method and writes output using the write methods noted above. See some of the included plugins, such as L for examples. Any attributes in the plugin should be prefixed with the name of the plugin, to avoid any conflicts with attribute and method names from other plugins, e.g. use Types::Standard qw/ Int /; has 'myplugin_heading_level' => ( is => 'rw', isa => Int, default => 1, lazy => 1, ); Attributes should be lazy to ensure that their defaults are properly set. Be aware that changing default values of an attribute based on arguments means that the next time a plugin method is run, the defaults will be changed. Custom types in L may be useful for attributes when writing plugins, e.g. use Pod::Readme::Types qw/ File HeadingLevel /; has 'myplugin_file' => ( is => 'rw', isa => File, coerce => sub { File->coerce(@_) }, default => 'Changes', lazy => 1, ); # We add this file to the list of dependencies around 'depends_on' => sub { my ($orig, $self) = @_; return ($self->myplugin_file, $self->$orig); }; =head1 ATTRIBUTES =head2 C The number of columns to indent a verbatim paragraph. =cut has verbatim_indent => ( is => 'ro', isa => Indentation, default => 2, ); =head1 METHODS =cut sub _parse_arguments { my ( $self, $line ) = @_; my @args = (); my $i = 0; my $prev; my $in_quote = ''; my $arg_buff = ''; while ( $i < length($line) ) { my $curr = substr( $line, $i, 1 ); if ( $curr !~ m/\s/ || $in_quote ) { $arg_buff .= $curr; if ( $curr =~ /["']/ && $prev ne "\\" ) { $in_quote = ( $curr eq $in_quote ) ? '' : $curr; } } elsif ( $arg_buff ne '' ) { push @args, $arg_buff; $arg_buff = ''; } $prev = $curr; $i++; } if ( $arg_buff ne '' ) { push @args, $arg_buff; } return @args; } =head2 C my $hash_ref = $self->parse_cmd_args( \@allowed_keys, @args); This command parses arguments for a plugin and returns a hash reference containing the argument values. The C<@args> parameter is a list of arguments passed to the command method by L. If an argument contains an equals sign, then it is assumed to take a string. (Strings containing whitespace should be surrounded by quotes.) Otherwise, an argument is assumed to be boolean, which defaults to true. If the argument is prefixed by "no-" or "no_" then it is given a false value. If the C<@allowed_keys> parameter is given, then it will reject argument keys that are not in that list. For example, my $res = $self->parse_cmd_args( undef, 'arg1', 'no-arg2', 'arg3="This is a string"', 'arg4=value', ); will return a hash reference containing { arg1 => 1, arg2 => 0, arg3 => 'This is a string', arg4 => 'value', } =cut sub parse_cmd_args { my ( $self, $allowed, @args ) = @_; my ( $key, $val, %res ); while ( my $arg = shift @args ) { state $eq = qr/=/; if ( $arg =~ $eq ) { ( $key, $val ) = split $eq, $arg; # TODO - better way to remove surrounding quotes if ( ( $val =~ /^(['"])(.*)(['"])$/ ) && ( $1 eq $3 ) ) { $val = $2 // ''; } } else { $val = 1; if ( ($key) = ( $arg =~ /^no[_-](\w+(?:[-_]\w+)*)$/ ) ) { $val = 0; } else { $key = $arg; } } $res{$key} = $val; } if ($allowed) { try { lock_keys( %res, @{$allowed} ); } catch { if (/Hash has key '(.+)' which is not in the new key set/) { die sprintf( "Invalid argument key '\%s'\n", $1 ); } else { die "Unknown error checking argument keys\n"; } }; } return \%res; } =head2 C $self->write_verbatim($text); A utility method to write verbatim text, indented by L. =cut sub write_verbatim { my ( $self, $text ) = @_; my $indent = ' ' x ( $self->verbatim_indent ); $text =~ s/^/${indent}/mg; $text =~ s/([^\n])\n?$/$1\n\n/; $self->write($text); } =begin :internal =head2 C<_write_cmd> $self->_write_cmd('=head1 SECTION'); An internal utility method to write a command line. =end :internal =cut sub _write_cmd { my ( $self, $text ) = @_; $text =~ s/([^\n])\n?$/$1\n\n/; $self->write($text); } =head2 C $self->write_para('This is a paragraph'); Utility method to write a POD paragraph. =cut sub write_para { my ( $self, $text ) = @_; $text //= ''; $self->write( $text . "\n\n" ); } =head2 C =head2 C =head2 C =head2 C =head2 C =head2 C =head2 C =head2 C =head2 C =head2 C =head2 C =head2 C =head2 C $self->write_head1($text); Utility methods to write POD specific commands to the C. These methods ensure the POD commands have extra newlines for compatibility with older POD parsers. =cut { foreach my $cmd ( qw/ head1 head2 head3 head4 over item begin end for encoding / ) { fresh( "write_${cmd}" => sub { my ( $self, $text ) = @_; $text //= ''; $self->_write_cmd( '=' . $cmd . ' ' . $text ); } ); } foreach my $cmd (qw/ pod back cut /) { fresh( "write_${cmd}" => sub { my ($self) = @_; $self->_write_cmd( '=' . $cmd ); } ); } } use namespace::autoclean; 1; Pod-Readme-v1.2.3/lib/Pod/Readme/Filter.pm0000644000175000017500000002204013366431456015731 0ustar rrrrpackage Pod::Readme::Filter; use v5.10.1; use Moo; our $VERSION = 'v1.2.3'; use MooX::HandlesVia; with 'Pod::Readme::Plugin'; use Carp; use File::Slurp qw/ read_file /; use IO qw/ File Handle /; use Module::Load qw/ load /; use Path::Tiny; use Try::Tiny; use Types::Standard qw/ Bool InstanceOf Int RegexpRef Str /; use Pod::Readme::Types qw/ Dir File ReadIO WriteIO TargetName DistZilla /; =head1 NAME Pod::Readme::Filter - Filter README from POD =head1 SYNOPSIS use Pod::Readme::Filter; my $prf = Pod::Readme::Filter->new( target => 'readme', base_dir => '.', input_file => 'lib/MyApp.pm', output_file => 'README.pod', ); =head1 DESCRIPTION This module provides the basic filtering and minimal processing to extract a F from a module's POD. It is used internally by L. =cut has encoding => ( is => 'ro', isa => Str, default => ':utf8', ); has base_dir => ( is => 'ro', isa => Dir, coerce => sub { Dir->coerce(@_) }, default => '.', ); has input_file => ( is => 'ro', isa => File, required => 0, coerce => sub { File->coerce(@_) }, ); has output_file => ( is => 'ro', isa => File, required => 0, coerce => sub { File->coerce(@_) }, ); has input_fh => ( is => 'ro', isa => ReadIO, lazy => 1, builder => '_build_input_fh', coerce => sub { ReadIO->coerce(@_) }, ); sub _build_input_fh { my ($self) = @_; if ( $self->input_file ) { $self->input_file->openr; } else { my $fh = IO::Handle->new; if ( $fh->fdopen( fileno(STDIN), 'r' ) ) { return $fh; } else { croak "Cannot get a filehandle for STDIN"; } } } has output_fh => ( is => 'ro', isa => WriteIO, lazy => 1, builder => '_build_output_fh', coerce => sub { WriteIO->coerce(@_) }, ); sub _build_output_fh { my ($self) = @_; if ( $self->output_file ) { $self->output_file->openw; } else { my $fh = IO::Handle->new; if ( $fh->fdopen( fileno(STDOUT), 'w' ) ) { return $fh; } else { croak "Cannot get a filehandle for STDOUT"; } } } has target => ( is => 'ro', isa => TargetName, default => 'readme', ); has in_target => ( is => 'ro', isa => Bool, init_arg => undef, default => 1, writer => '_set_in_target', ); has _target_regex => ( is => 'ro', isa => RegexpRef, init_arg => undef, lazy => 1, default => sub { my $self = shift; my $target = $self->target; qr/^[:]?${target}$/; }, ); has mode => ( is => 'rw', isa => Str, default => 'default', init_arg => undef, ); has _line_no => ( is => 'ro', isa => Int, default => 0, writer => '_set_line_no', ); sub _inc_line_no { my ($self) = @_; $self->_set_line_no( 1 + $self->_line_no ); } sub depends_on { my ($self) = @_; my @files; push @files, $self->input_file if $self->input_file; return @files; } sub write { my ( $self, $line ) = @_; my $fh = $self->output_fh; print {$fh} $line; } sub in_pod { my ($self) = @_; $self->mode eq 'pod'; } has _for_buffer => ( is => 'rw', isa => Str, init_arg => undef, default => '', handles_via => 'String', handles => { _append_for_buffer => 'append', _clear_for_buffer => 'clear', }, ); has _begin_args => ( is => 'rw', isa => Str, init_arg => undef, default => '', handles_via => 'String', handles => { _clear_begin_args => 'clear', }, ); has zilla => ( is => 'ro', isa => InstanceOf[ 'Dist::Zilla' ], ); sub process_for { my ( $self, $data ) = @_; my ( $target, @args ) = $self->_parse_arguments($data); if ( $target && $target =~ $self->_target_regex ) { if ( my $cmd = shift @args ) { $cmd =~ s/-/_/g; if ( my $method = $self->can("cmd_${cmd}") ) { try { $self->$method(@args); } catch { s/\n$//; die sprintf( "\%s at input line \%d\n", $_, $self->_line_no ); }; } else { die sprintf( "Unknown command: '\%s' at input line \%d\n", $cmd, $self->_line_no ); } } } $self->_clear_for_buffer; } sub filter_line { my ( $self, $line ) = @_; # Modes: # # pod = POD mode # # pod:for = buffering text for =for command # # pod:begin = don't print this line, skip next line # # target:* = begin block for something other than readme # # default = code # state $blank = qr/^\s*\n$/; my $mode = $self->mode; if ( $mode eq 'pod:for' ) { if ( $line =~ $blank ) { $self->process_for( $self->_for_buffer ); $mode = $self->mode('pod'); } else { $self->_append_for_buffer($line); } return 1; } elsif ( $mode eq 'pod:begin' ) { unless ( $line =~ $blank ) { die sprintf( "Expected new paragraph after command at line \%d\n", $self->_line_no ); } $self->mode('pod'); return 1; } if ( my ($cmd) = ( $line =~ /^=(\w+)\s/ ) ) { $mode = $self->mode( $cmd eq 'cut' ? 'default' : 'pod' ); if ( $self->in_pod ) { if ( $cmd eq 'for' ) { $self->mode('pod:for'); $self->_for_buffer( substr( $line, 4 ) ); } elsif ( $cmd eq 'begin' ) { my ( $target, @args ) = $self->_parse_arguments( substr( $line, 6 ) ); if ( $target =~ $self->_target_regex ) { if (@args) { my $buffer = join( ' ', @args ); if ( substr( $target, 0, 1 ) eq ':' ) { die sprintf( "Can only target POD at line \%d\n", $self->_line_no + 1 ); } $self->write_begin( $self->_begin_args($buffer) ); } $self->mode('pod:begin'); } else { $self->mode( 'target:' . $target ); } } elsif ( $cmd eq 'end' ) { my ( $target, @args ) = $self->_parse_arguments( substr( $line, 4 ) ); if ( $target =~ $self->_target_regex ) { my $buffer = $self->_begin_args; if ( $buffer ne '' ) { $self->write_end($buffer); $self->_clear_begin_args; } } $self->mode('pod:begin'); } } } $self->write($line) if $self->in_target && $self->in_pod; return 1; } sub filter_file { my ($self) = @_; foreach my $line ( read_file( $self->input_fh, binmode => $self->encoding ) ) { $self->filter_line($line) or last; $self->_inc_line_no; } } sub run { my ($self) = @_; $self->filter_file; } sub cmd_continue { my ($self) = @_; $self->cmd_start; } sub cmd_include { my ( $self, @args ) = @_; my $res = $self->parse_cmd_args( [qw/ file type start stop /], @args ); my $start = $res->{start}; $start = qr/${start}/ if $start; my $stop = $res->{stop}; $stop = qr/${stop}/ if $stop; my $type = $res->{type} // 'pod'; unless ( $type =~ /^(?:text|pod)$/ ) { die "Unsupported include type: '${type}'\n"; } my $file = $res->{file}; my $fh = IO::File->new( $file, 'r' ) or die "Unable to open file '${file}': $!\n"; $self->write("\n"); while ( my $line = <$fh> ) { next if ( $start && $line !~ $start ); last if ( $stop && $line =~ $stop ); $start = undef; if ( $type eq 'text' ) { $self->write_verbatim($line); } else { $self->write($line); } } $self->write("\n"); close $fh; } sub cmd_start { my ($self) = @_; $self->_set_in_target(1); } sub cmd_stop { my ($self) = @_; $self->_set_in_target(0); } sub _load_plugin { my ( $self, $plugin ) = @_; try { my $module = "Pod::Readme::Plugin::${plugin}"; load $module; require Role::Tiny; Role::Tiny->apply_roles_to_object( $self, $module ); } catch { die "Unable to locate plugin '${plugin}': $_"; }; } sub cmd_plugin { my ( $self, $plugin, @args ) = @_; my $name = "cmd_${plugin}"; $self->_load_plugin($plugin) unless $self->can($name); if ( my $method = $self->can($name) ) { $self->$method(@args); } } use namespace::autoclean; 1; Pod-Readme-v1.2.3/lib/Pod/Readme/Plugin/0000775000175000017500000000000013366431456015410 5ustar rrrrPod-Readme-v1.2.3/lib/Pod/Readme/Plugin/requires.pm0000644000175000017500000001236413366431456017611 0ustar rrrrpackage Pod::Readme::Plugin::requires; use Moo::Role; our $VERSION = 'v1.2.3'; use CPAN::Meta; use Module::CoreList; use Path::Tiny; use Types::Standard qw/ Bool Str /; use Pod::Readme::Types qw/ File HeadingLevel /; =head1 NAME Pod::Readme::Plugin::requires - Include requirements in README =head1 SYNOPSIS =for readme plugin requires =head1 DESCRIPTION This is a plugin for L that includes module requirements from the F file. Because this depends on the F file, the F should be generated after that file has been updated. =head1 ARGUMENTS =head2 C =for readme plugin version from-file='MYMETA.yml' By default, it will extract the version from the F file. If, for some reason, this file is in a non-standard location, then you should specify it here. The file will be ignored if the C attribute is set, and instead obtain metadata from the L object (since the F file may not exist.) =head2 C By default, core modules for the version of Perl specified in the F file are omitted from this list. If you prefer to lise all requirements, then specify this option. =head2 C =for readme plugin version title='REQUIREMENTS' This argument allows you to change the title of the heading. =head1 KNOWN ISSUES =over =item * Trailing zeros in module versions may be dropped. If you specify a minimum version of a module with a trailing zero, e.g. "0.30", then it may be shown as "0.3". A workaround is to specify the module version in your F<Makefile.PL> as a string instead of number: requires( 'CPAN::Changes' => '0.30', ... ); =back =cut requires 'parse_cmd_args'; has 'requires_from_file' => ( is => 'rw', isa => File, coerce => sub { File->coerce(@_) }, default => 'META.yml', lazy => 1, ); has 'requires_title' => ( is => 'rw', isa => Str, default => 'REQUIREMENTS', lazy => 1, ); has 'requires_omit_core' => ( is => 'rw', isa => Bool, default => 1, lazy => 1, ); has 'requires_heading_level' => ( is => 'rw', isa => HeadingLevel, default => 1, lazy => 1, ); has 'requires_run' => ( is => 'rw', isa => Bool, default => 0, lazy => 1, ); around 'depends_on' => sub { my ( $orig, $self ) = @_; return ( $self->requires_from_file, $self->$orig ); }; sub cmd_requires { my ( $self, @args ) = @_; die "The requires plugin can only be used once" if $self->requires_run; my $res = $self->parse_cmd_args( [qw/ from-file title omit-core no-omit-core heading-level /], @args ); foreach my $key ( keys %{$res} ) { ( my $name = "requires_${key}" ) =~ s/-/_/g; if ( my $method = $self->can($name) ) { $self->$method( $res->{$key} ); } else { die "Invalid key: '${key}'"; } } my $meta; if ( $self->zilla ) { $meta = CPAN::Meta->create( $self->zilla->distmeta, { lazy_validation => 1 } ); } else { my $file = path( $self->base_dir, $self->requires_from_file )->stringify; unless ( -e $file ) { die "Cannot find META.yml file at '${file}"; } $meta = CPAN::Meta->load_file($file); } my ( $prereqs, $perl ) = $self->_get_prereqs( $meta, 'requires' ); if ( %{$prereqs} ) { my $heading = $self->can( "write_head" . $self->requires_heading_level ) or die "Invalid heading level: " . $self->requires_heading_level; $self->$heading( $self->requires_title ); if ($perl) { $self->write_para( sprintf( 'This distribution requires Perl %s.', version->parse($perl)->normal ) ); } $self->write_para('This distribution requires the following modules:'); $self->_write_modules($prereqs); my ($recommends) = $self->_get_prereqs( $meta, 'recommends' ); if ( %{$recommends} ) { $self->write_para( 'This distribution recommends the following modules:'); $self->_write_modules($recommends); } } $self->requires_run(1); } sub _get_prereqs { my ( $self, $meta, $key ) = @_; my %prereqs; foreach my $type ( values %{ $meta->prereqs } ) { # TODO: max version $prereqs{$_} = $type->{$key}->{$_} for ( keys %{ $type->{$key} } ); } my $perl = delete $prereqs{perl}; if ( $self->requires_omit_core && $perl ) { foreach ( keys %prereqs ) { my $ver = $prereqs{$_}; delete $prereqs{$_} if Module::CoreList->first_release( $_, $prereqs{$ver} ) && version->parse( Module::CoreList->first_release($_) ) <= version->parse($perl); } } return ( \%prereqs, $perl ); } sub _write_modules { my ( $self, $prereqs ) = @_; $self->write_over(4); foreach my $module ( sort { lc($a) cmp lc($b) } keys %{$prereqs} ) { my $version = $prereqs->{$module}; my $text = $version ? " (version ${version})" : ''; $self->write_item( sprintf( '* L<%s>', $module ) . $text ); } $self->write_back; } use namespace::autoclean; 1; ����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Pod-Readme-v1.2.3/lib/Pod/Readme/Plugin/changes.pm��������������������������������������������������0000644�0001750�0001750�00000007367�13366431456�017371� 0����������������������������������������������������������������������������������������������������ustar �rr������������������������������rr���������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������package Pod::Readme::Plugin::changes; use Moo::Role; our $VERSION = 'v1.2.3'; use CPAN::Changes 0.30; use Path::Tiny; use Types::Standard qw/ Bool Str /; use Pod::Readme::Types qw/ File HeadingLevel /; =head1 NAME Pod::Readme::Plugin::changes - Include latest Changes in README =head1 SYNOPSIS =for readme plugin changes =head1 DESCRIPTION This is a plugin for L<Pod::Readme> that includes the latest release of a F<Changes> file that conforms to the L<CPAN::Changes::Spec>. =head1 ARGUMENTS Defaults can be overridden with optional arguments. Note that changing arguments may change later calls to this plugin. =head2 C<file> =for readme plugin changes file='Changes' If the F<Changes> file has a non-standard name or location in the distribution, you can specify an alternative name. But note that it I<must> conform the the L<CPAN::Changes::Spec>. =head2 C<heading-level> =for readme plugin changes heading-level=1 This changes the heading level. (The default is 1.) =head2 C<title> =for readme plugin changes title='RECENT CHANGES' This option allows you to change the title of the heading. =head2 C<verbatim> =for readme plugin changes verbatim If you prefer, you can display a verbatim section of the F<Changes> file. By default, the F<Changes> file will be parsed and reformatted as POD (equivalent to the C<no-verbatim> option). =cut requires 'parse_cmd_args'; has 'changes_file' => ( is => 'rw', isa => File, coerce => sub { File->coerce(@_) }, default => 'Changes', lazy => 1, ); has 'changes_title' => ( is => 'rw', isa => Str, default => 'RECENT CHANGES', lazy => 1, ); has 'changes_verbatim' => ( is => 'rw', isa => Bool, default => 0, lazy => 1, ); has 'changes_heading_level' => ( is => 'rw', isa => HeadingLevel, default => 1, lazy => 1, ); has 'changes_run' => ( is => 'rw', isa => Bool, default => 0, lazy => 1, ); around 'depends_on' => sub { my ($orig, $self) = @_; return ($self->changes_file, $self->$orig); }; sub cmd_changes { my ( $self, @args ) = @_; die "The changes plugin can only be used once" if $self->changes_run; my $res = $self->parse_cmd_args( [qw/ file title verbatim no-verbatim heading-level /], @args ); foreach my $key ( keys %{$res} ) { ( my $name = "changes_${key}" ) =~ s/-/_/g; if ( my $method = $self->can($name) ) { $self->$method( $res->{$key} ); } else { die "Invalid key: '${key}'"; } } my $file = path( $self->base_dir, $self->changes_file ); my %opts; if ($self->zilla) { $opts{next_token} = qr/\{\{\$NEXT}}/; } my $changes = CPAN::Changes->load($file, %opts); my $latest = ( $changes->releases )[-1]; my $heading = $self->can( "write_head" . $self->changes_heading_level ) or die "Invalid heading level: " . $self->changes_heading_level; $self->$heading( $self->changes_title ); if ( $self->changes_verbatim ) { $self->write_verbatim( $latest->serialize ); } else { foreach my $group ( $latest->groups ) { $self->write_head2($group) if ( $group ne '' ); $self->write_over(4); foreach my $items ( $latest->get_group($group)->changes ) { foreach my $item ( @{$items} ) { $self->write_item('* '); $self->write_para($item); } } $self->write_back(); } } $self->write_para( sprintf( 'See the F<%s> file for a longer revision history.', $file->basename ) ); $self->changes_run(1); } use namespace::autoclean; 1; �������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Pod-Readme-v1.2.3/lib/Pod/Readme/Plugin/version.pm��������������������������������������������������0000644�0001750�0001750�00000004571�13366431456�017440� 0����������������������������������������������������������������������������������������������������ustar �rr������������������������������rr���������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������package Pod::Readme::Plugin::version; use Moo::Role; our $VERSION = 'v1.2.3'; use ExtUtils::MakeMaker; use Types::Standard qw/ Bool Str /; use Pod::Readme::Types qw/ File HeadingLevel /; =head1 NAME Pod::Readme::Plugin::version - Include version in README =head1 SYNOPSIS =for readme plugin version =head1 DESCRIPTION This is a plugin for L<Pod::Readme> that includes the release version. =head1 ARGUMENTS =head2 C<file> =for readme plugin version file='lib/My/App.pm' By default, it will extract the version from the same file that the F<README> is being extracted from. If this is a different file, then it should be specified. =head2 C<title> =for readme plugin version title='VERSION' This argument allows you to change the title of the heading. =cut requires 'parse_cmd_args'; has 'version_file' => ( is => 'rw', isa => File, required => 0, coerce => sub { File->coerce(@_) }, lazy => 1, default => sub { my ($self) = @_; $self->input_file; }, ); has 'version_title' => ( is => 'rw', isa => Str, default => 'VERSION', lazy => 1, ); has 'version_heading_level' => ( is => 'rw', isa => HeadingLevel, default => 1, lazy => 1, ); has 'version_run' => ( is => 'rw', isa => Bool, default => 0, lazy => 1, ); around 'depends_on' => sub { my ($orig, $self) = @_; return ($self->version_file, $self->$orig); }; sub cmd_version { my ( $self, @args ) = @_; die "The version plugin can only be used once" if $self->version_run; my $res = $self->parse_cmd_args( [qw/ file title heading-level /], @args ); foreach my $key ( keys %{$res} ) { ( my $name = "version_${key}" ) =~ s/-/_/g; if ( my $method = $self->can($name) ) { $self->$method( $res->{$key} ); } else { die "Invalid key: '${key}'"; } } if ( my $file = $self->version_file ) { my $heading = $self->can( "write_head" . $self->version_heading_level ) or die "Invalid heading level: " . $self->version_heading_level; $self->$heading( $self->version_title ); $self->write_para( MM->parse_version($file) ); $self->version_run(1); } else { die "Don't know what file to determine the version from"; } } use namespace::autoclean; 1; ���������������������������������������������������������������������������������������������������������������������������������������Pod-Readme-v1.2.3/lib/Pod/Readme/Types.pm�����������������������������������������������������������0000644�0001750�0001750�00000006731�13366431456�015621� 0����������������������������������������������������������������������������������������������������ustar �rr������������������������������rr���������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������package Pod::Readme::Types; use v5.10.1; use feature 'state'; use strict; use warnings; our $VERSION = 'v1.2.3'; use Exporter qw/ import /; use IO qw/ Handle /; use Path::Tiny; use Scalar::Util qw/ blessed /; use Type::Tiny 1.000000; use Types::Standard qw/ FileHandle Str /; # RECOMMEND PREREQ: Type::Tiny::XS our @EXPORT_OK = qw/ Dir File Indentation IO ReadIO WriteIO HeadingLevel TargetName DistZilla /; =head1 NAME Pod::Readme::Types - Types used by Pod::Readme =head1 SYNOPSIS use Pod::Readme::Types qw/ Indentation /; has verbatim_indent => ( is => 'ro', isa => Indentation, default => 2, ); =head1 DESCRIPTION This module provides types for use with the modules in L<Pod::Readme>. It is intended for internal use, although some of these may be useful for writing plugins (see L<Pod::Readme::Plugin>). =head1 EXPORTS None by default. All functions must be explicitly exported. =head2 C<Indentation> The indentation level used for verbatim text. Must be an integer greater than or equal to 2. =cut sub Indentation { state $type = Type::Tiny->new( name => 'Indentation', constraint => sub { $_ =~ /^\d+$/ && $_ >= 2 }, message => sub { 'must be an integer >= 2' }, ); return $type; } =head2 C<HeadingLevel> A heading level, used for plugin headings. Must be either 1, 2 or 3. (Note that C<=head4> is not allowed, since some plugins use subheadings.) =cut sub HeadingLevel { state $type = Type::Tiny->new( name => 'HeadingLevel', constraint => sub { $_ =~ /^[123]$/ }, message => sub { 'must be an integer between 1 and 3' }, ); return $type; } =head2 C<TargetName> A name of a target, e.g. "readme". =cut sub TargetName { state $type = Type::Tiny->new( name => 'TargetName', constraint => sub { $_ =~ /^\w+$/ }, message => sub { 'must be an alphanumeric string' }, ); return $type; } =head2 C<Dir> A directory. Can be a string or L<Path::Tiny> object. =cut sub Dir { state $type = Type::Tiny->new( name => 'Dir', constraint => sub { blessed($_) && $_->isa('Path::Tiny') && -d $_; }, message => sub { "$_ must be be a directory" }, ); return $type->plus_coercions( Str, sub { path($_) }, ); } =head2 C<File> A file. Can be a string or L<Path::Tiny> object. =cut sub File { state $type = Type::Tiny->new( name => 'File', constraint => sub { blessed($_) && $_->isa('Path::Tiny'); }, message => sub { "$_ must be be a file" }, ); return $type->plus_coercions( Str, sub { path($_) }, ); } =head2 C<IO> An L<IO::Handle> or L<IO::String> object. =cut sub IO { state $type = Type::Tiny->new( name => 'IO', constraint => sub { blessed($_) && ( $_->isa('IO::Handle') || $_->isa('IO::String') ); }, message => sub { 'must be be an IO::Handle or IO::String' }, ); return $type; } =head2 C<ReadIO> =head2 C<WriteIO> L</IO> types, which coerce filehandles to read/write L<IO:Handles>, respectively. =cut sub ReadIO { state $type = IO->plus_coercions( # FileHandle, sub { IO::Handle->new_from_fd( $_, 'r' ) }, ); return $type; } sub WriteIO { state $type = IO->plus_coercions( # FileHandle, sub { IO::Handle->new_from_fd( $_, 'w' ) }, ); return $type; } 1; ���������������������������������������Pod-Readme-v1.2.3/lib/Pod/Readme.pm�����������������������������������������������������������������0000644�0001750�0001750�00000024744�13366431456�014521� 0����������������������������������������������������������������������������������������������������ustar �rr������������������������������rr���������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������package Pod::Readme; =head1 NAME Pod::Readme - Intelligently generate a README file from POD =for readme plugin version =head1 SYNOPSIS In a module's POD: =head1 NAME MyApp - my nifty app =for readme plugin version =head1 DESCRIPTION This is a nifty app. =begin :readme =for readme plugin requires =head1 INSTALLATION ... =end :readme =for readme stop =head1 METHODS ... Then from the command-line: pod2readme lib/MyModule.pm README =for readme stop From within Perl: use Pod::Readme; my $prf = Pod::Readme->new( input_file => 'lib/MyModule.pm', translate_to_file => $dest, translation_class => 'Pod::Simple::Text', ); $prf->run(); =for readme start =head1 DESCRIPTION This module filters POD to generate a F<README> file, by using POD commands to specify which parts are included or excluded from the F<README> file. =begin :readme See the L<Pod::Readme> documentation for more details on the POD syntax that this module recognizes. See L<pod2readme> for command-line usage. =head1 INSTALLATION See L<How to install CPAN modules|http://www.cpan.org/modules/INSTALL.html>. =for readme plugin requires heading-level=2 title="Required Modules" =for readme plugin changes =end :readme =for readme stop =head1 POD COMMANDS =head2 C<=for readme stop> Stop including the POD that follows in the F<README>. =head2 C<=for readme start> =head2 C<=for readme continue> Start (or continue to) include the POD that follows in the F<README>. Note that the C<start> command was added as a synonym in version 1.0.0. =head2 C<=for readme include> =for readme include file="INSTALL" type="text" Include a text or POD file in the F<README>. It accepts the following options: =over =item C<file> Required. This is the file name to include. =item C<type> Can be "text" or "pod" (default). =item C<start> An optional regex of where to start including the file. =item C<stop> An optional regex of where to stop including the file. =back =head2 C<=for readme plugin> Loads a plugin, e.g. =for readme plugin version Note that specific plugins may add options, e.g. =for readme plugin changes title='CHANGES' See L<Pod::Readme::Plugin> for more information. Note that the C<plugin> command was added in version 1.0.0. =head2 C<=begin :readme> =head2 C<=end :readme> Specify a block of POD to include only in the F<README>. You can also specify a block in another format: =begin readme text ... =end readme text This will be translated into =begin text ... =end text and will only be included in F<README> files of that format. Note: earlier versions of this module suggested using =begin readme ... =end readme While this version supports that syntax for backwards compatibility, it is not standard POD. =cut use v5.10.1; use Moo; extends 'Pod::Readme::Filter'; our $VERSION = 'v1.2.3'; use Carp; use IO qw/ File Handle /; use List::Util 1.33 qw/ any /; use Module::Load qw/ load /; use Path::Tiny qw/ path tempfile /; use Pod::Simple; use Types::Standard qw/ Bool Maybe Str /; use Pod::Readme::Types qw/ File WriteIO /; # RECOMMEND PREREQ: Pod::Man # RECOMMEND PREREQ: Pod::Markdown # RECOMMEND PREREQ: Pod::Markdown::Github # RECOMMEND PREREQ: Pod::Simple::HTML # RECOMMEND PREREQ: Pod::Simple::LaTeX # RECOMMEND PREREQ: Pod::Simple::RTF # RECOMMEND PREREQ: Pod::Simple::Text # RECOMMEND PREREQ: Pod::Simple::XHTML =head1 ATTRIBUTES This module extends L<Pod::Readme::Filter> with the following attributes: =head2 C<translation_class> The class used to translate the filtered POD into another format, e.g. L<Pod::Simple::Text>. If it is C<undef>, then there is no translation. Only subclasses of L<Pod::Simple> are supported. =cut has translation_class => ( is => 'ro', isa => Maybe [Str], default => undef, ); =head2 C<translate_to_fh> The L<IO::Handle> to save the translated file to. =cut has translate_to_fh => ( is => 'ro', isa => WriteIO, lazy => 1, builder => '_build_translate_to_fh', coerce => sub { WriteIO->coerce(@_) }, ); sub _build_translate_to_fh { my ($self) = @_; if ( $self->translate_to_file ) { $self->translate_to_file->openw; } else { my $fh = IO::Handle->new; if ( $fh->fdopen( fileno(STDOUT), 'w' ) ) { return $fh; } else { croak "Cannot get a filehandle for STDOUT"; } } } =head2 C<translate_to_file> The L<Path::Tiny> filename to save the translated file to. If omitted, then it will be saved to C<STDOUT>. =cut has translate_to_file => ( is => 'ro', isa => File, coerce => sub { File->coerce(@_) }, lazy => 1, builder => 'default_readme_file', ); =head2 C<output_file> The L<Pod::Readme::Filter> C<output_file> will default to a temporary file. =cut has '+output_file' => ( lazy => 1, default => sub { tempfile( SUFFIX => '.pod', UNLINK => 1 ); }, ); around '_build_output_fh' => sub { my ( $orig, $self ) = @_; if ( defined $self->translation_class ) { $self->$orig(); } else { $self->translate_to_fh; } }; =head2 C<force> For a new F<README> to be generated, even if the dependencies have not been updated. See L</dependencies_updated>. =cut has 'force' => ( is => 'ro', isa => Bool, default => 0, ); =head2 C<zilla> For use with L<Dist::Zilla> plugins. This allows plugins which normally depend on files in the distribution to use metadata from here instead. =cut =head1 METHODS This module extends L<Pod::Readme::Filter> with the following methods: =head2 C<default_readme_file> The default name of the F<README> file, which depends on the L</translation_class>. =cut sub default_readme_file { my ($self) = @_; my $name = uc( $self->target ); state $extensions = { 'Pod::Man' => '.1', 'Pod::Markdown' => '.md', 'Pod::Simple::HTML' => '.html', 'Pod::Simple::LaTeX' => '.tex', 'Pod::Simple::RTF' => '.rtf', 'Pod::Simple::Text' => '', 'Pod::Simple::XHTML' => '.xhtml', }; my $class = $self->translation_class; if ( defined $class ) { if ( my $ext = $extensions->{$class} ) { $name .= $ext; } } else { $name .= '.pod'; } path( $self->base_dir, $name ); } =head2 C<translate_file> This method runs translates the resulting POD from C<filter_file>. =cut sub translate_file { my ($self) = @_; if ( my $class = $self->translation_class ) { load $class; my $converter = $class->new() or croak "Cannot instantiate a ${class} object"; if ( $converter->isa('Pod::Simple') ) { my $tmp_file = $self->output_file->stringify; close $self->output_fh or croak "Unable to close file ${tmp_file}"; $converter->output_fh( $self->translate_to_fh ); $converter->parse_file($tmp_file); } else { croak "Don't know how to translate POD using ${class}"; } } } =head2 C<dependencies_updated> Used to determine when the dependencies have been updated, and a translation can be run. Note that this only returns a meaningful value after the POD has been processed, since plugins may add to the dependencies. A side-effect of this is that when generating a POD formatted F<README> is that it will always be updated, even when L</force> is false. =cut sub dependencies_updated { my ($self) = @_; my $dest = $self->translate_to_file; if ( $dest and $self->input_file) { return 1 unless -e $dest; my $stat = $dest->stat; return 1 unless $stat; my $time = $stat->mtime; return any { $_->mtime > $time } ( map { $_->stat } $self->depends_on ); } else { return 1; } } =head2 C<run> This method runs C<filter_file> and then L</translate_file>. =cut around 'run' => sub { my ( $orig, $self ) = @_; $self->$orig(); if ( $self->force or $self->dependencies_updated ) { $self->translate_file(); } }; =head2 C<parse_from_file> my $parser = Pod::Readme->new(); $parser->parse_from_file( 'README.pod', 'README' ); Pod::Readme->parse_from_file( 'README.pod', 'README' ); This is a class method that acts as a L<Pod::Select> compatibility shim for software that is designed for versions of L<Pod::Readme> prior to v1.0. Its use is deprecated, and will be deleted in later versions. =cut sub parse_from_file { my ( $self, $source, $dest ) = @_; my $class = ref($self) || __PACKAGE__; my $prf = $class->new( input_file => $source, translate_to_file => $dest, translation_class => 'Pod::Simple::Text', force => 1, ); $prf->run(); } =head2 C<parse_from_filehandle> Like L</parse_from_file>, this exists as a compatibility shim. Its use is deprecated, and will be deleted in later versions. =cut sub parse_from_filehandle { my ( $self, $source_fh, $dest_fh ) = @_; my $class = ref($self) || __PACKAGE__; my $src_io = IO::Handle->new_from_fd( ( defined $source_fh ) ? fileno($source_fh) : 0, 'r' ); my $dest_io = IO::Handle->new_from_fd( ( defined $dest_fh ) ? fileno($dest_fh) : 1, 'w' ); my $prf = $class->new( input_fh => $src_io, translate_to_fh => $dest_io, translation_class => 'Pod::Simple::Text', force => 1, ); $prf->run(); } use namespace::autoclean; 1; =for readme start =head1 CAVEATS This module is intended to be used by module authors for their own modules. It is not recommended for generating F<README> files from arbitrary Perl modules from untrusted sources. =head1 SEE ALSO See L<perlpod>, L<perlpodspec> and L<podlators>. =head1 AUTHORS The original version was by Robert Rothenberg <rrwo@cpan.org> until 2010, when maintenance was taken over by David Precious <davidp@preshweb.co.uk>. In 2014, Robert Rothenberg rewrote the module to use filtering instead of subclassing a POD parser. =head2 Acknowledgements Thanks to people who gave feedback and suggestions to posts about the rewrite of this module on L<http://blogs.perl.org>. =head2 Suggestions, Bug Reporting and Contributing This module is developed on GitHub at L<http://github.com/bigpresh/Pod-Readme> =head1 LICENSE Copyright (c) 2005-2014 Robert Rothenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut ����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������