/ 
App-podweaver-0.99_02
River stage zero No dependents
/ App::podweaver

NAME

App::podweaver - Run Pod::Weaver on the files within a distribution.

VERSION

version 0.99_02

SYNOPSIS

App::podweaver provides a mechanism to run Pod::Weaver over the files within a distribution, without needing to use Dist::Zilla.

Where Dist::Zilla works on a copy of your source code, App::podweaver is intended to modify your source code directly, and as such it is highly recommended that you use the Pod::Weaver::PluginBundle::ReplaceBoilerplate plugin bundle so that you over-write existing POD sections, instead of the default Pod::Weaver behaviour of repeatedly appending.

You can configure the Pod::Weaver invocation by providinng a weaver.ini file in the root directory of your distribution.

BOOTSTRAPPING WITH META.json/META.yml

Since the META.json/yml file is often generated with an abstract extracted from the POD, and App::podweaver expects a valid META file for some of the information to insert into the POD, there's a chicken-and-egg situation on the first invocation of either.

Running App::podweaver first should produce a POD with an abstract line populated from your # ABSTRACT: header, but without additional sections like version and authors. You can then generate your META file as per usual, and then run App::podweaver again to produce the missing sections:

$ ./Build distmeta
Creating META.yml
ERROR: Missing required field 'dist_abstract' for metafile
$ podweaver -v
No META.json or META.yml file found, are you running in a distribution directory?
Processing lib/App/podweaver.pm
$ ./Build distmeta
Creating META.yml
$ podweaver -v
Processing lib/App/podweaver.pm

This should only be neccessary on newly created distributions as both the META and the neccessary POD abstract should be present subsequently.

METHODS

$success = App::podweaver->weave_file( %options )

Runs Pod::Weaver on the given file, merges the generated Pod back into the appropriate place and writes the new file out.

App::podweaver->weave_file() returns App::podweaver::FAIL on failure, and either App::podweaver::SUCCESS_UNCHANGED or App::podweaver::SUCCESS_CHANGED on success, depending on whether changes needed to be made as a result of the weaving.

Currently these constants are not exportable.

The following options configure App::podweaver->weave_file():

filename => $filename (required)

The filename of the file to weave.

weaver => $weaver (required)

The Pod::Weaver instance to use for the weaving.

no_backup => 0 | 1 (default: 0)

If set to a true value, no backup will be made of the original file.

new => 0 | 1 (default: 0)

If set to a true value, the modified file will be written to the original filename with .new appended, rather than overwriting the original.

dist_version => $version

If no $VERSION can be parsed from the file by Module::Build::ModuleInfo, the version supplied in dist_version will be used as a fallback.

Any additional options are passed untouched to Pod::Weaver.

$dist_info = App::podweaver->get_dist_info( %options )

Attempts to extract the information needed by Pod::Weaver about the distribution.

It does this by examining any META.json or META.yml file it finds, and by expanding various fields found within.

Valid options are:

dist_root => $directory (default: current working directory)

Treats $directory as the root directory of the distribution, where the META.json or META.yml file should be found.

If not supplied, this will default to the current working directory.

antispam => $string

If set, any @ sign in author emails will be replaced by a space, the given string, and a further space, in an attempt to confuse spammers.

For example antispam => 'NOSPAM' will transform an email of nobody@127.0.0.1 into nobody NOSPAM 127.0.0.1.

$weaver = App::podweaver->get_weaver( %options )

Builds a Pod::Weaver instance, attemping to find a weaver.ini in the distribution root directory.

Valid options are:

dist_root => $directory (default: current working directory)

Treats $directory as the root directory of the distribution, where the weaver.ini file should be found.

If not supplied, this will default to the current working directory.

@files = App::podweaver->find_files_to_weave( %options )

Invokes File::Find::Rule, File::Find::Rule::VCS and File::Find::Rule::Perl to return a list of perl files that are candidates to run Pod::Weaver on in the lib, bin and script dirs of the distribution directory.

Valid options are:

dist_root => $directory (default: current working directory)

Treats $directory as the root directory of the distribution.

If not supplied, this will default to the current working directory.

App::podweaver->weave_distribution( %options )

Rolls all the other methods together to run Pod::Weaver on the appropriate files within the distribution found in the current working directory.

$config = App::podweaver->config()

Retrieves the Config::Tiny contents of the user's config file for the application, as found in the podweaver.ini file in the usual place for user configuration files for your OS.

(~/.app_podweaver/podweaver.ini for UNIX, ~/Local Settings/Application Data/App-podweaver/podweaver.ini under Windows.)

KNOWN ISSUES AND BUGS

Currently skips files without package declaration.

Pod::Weaver::Plugin::Name croaks if there's no package declaration in the file, preventing Pod::Weaver from running over scripts and .pod files at this time. App::podweaver currently avoids trying to run on files that will trigger this problem.

META.json/yml bootstrap is a mess

The whole bootstrap issue with META.json/yml is ugly.

REPORTING BUGS

Please report any bugs or feature requests to bug-app-podweaver at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-podweaver. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::podweaver

You can also look for information at:

AUTHOR

Sam Graham <libapp-podweaver-perl BLAHBLAH illusori.co.uk>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Sam Graham <libapp-podweaver-perl BLAHBLAH illusori.co.uk>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.