NAME

Pod::Weaver::Section::AllowOverride - Allow POD to override a Pod::Weaver-provided section

VERSION

This document describes version 0.05 of Pod::Weaver::Section::AllowOverride, released May 5, 2014.

SYNOPSIS

[Authors]
[AllowOverride]
header_re = ^AUTHORS?$
action    = replace ; this is the default
match_anywhere = 0  ; this is the default

DESCRIPTION

Sometimes, you might want to override a normally-generic section in one of your modules. This section plugin replaces the preceding section with the corresponding section taken from your POD (if it exists). If your POD doesn't contain a matching section, then the Pod::Weaver-provided one will be used.

Both the original section in your POD and the section provided by Pod::Weaver must match the header_re. Also, this plugin must immediately follow the section you want to replace (unless you set match_anywhere to a true value).

It's a similar idea to Pod::Weaver::Role::SectionReplacer, except that it works the other way around. SectionReplacer replaces the section from your POD with a section provided by Pod::Weaver.

ATTRIBUTES

header_re

This regular expression is used to select the section you want to override. It's matched against the section name from the =head1 line. The default is an exact match with the name of this plugin. (e.g. if the plugin name is AUTHOR, the default would be ^AUTHOR$)

action

This controls what to do when both a Pod::Weaver-provided section and a POD-provided section are found. It must be one of the following values:

replace

Replace the Pod::Weaver-provided section with the POD-provided one. (This is the default.)

prepend

Place the POD-provided section at the beginning of the Pod::Weaver-provided one. The POD-provided header is used, and the Pod::Weaver-provided header is discarded.

append

Place the POD-provided section at the end of the Pod::Weaver-provided one. The POD-provided header is used, and the Pod::Weaver-provided header is discarded.

match_anywhere

By default, AllowOverride must immediately follow the section to be overriden in your weaver.ini. If you set match_anywhere to a true value, then it can come anywhere after the section to be overriden (i.e. there can be other sections in between). AllowOverride will search backwards for a section matching header_re, and die if there is no such section.

This is useful if the section you want to override comes from a bundle.

SEE ALSO

Pod::Weaver::Role::SectionReplacer, Pod::Weaver::PluginBundle::ReplaceBoilerplate

BUGS

Please report any bugs or feature requests to bug-pod-weaver-section-allowoverride@rt.cpan.org or through the web interface at: http://rt.cpan.org/Public/Dist/Display.html?Name=Pod-Weaver-Section-AllowOverride

AUTHOR

Christopher J. Madsen <perl@cjmweb.net>

SOURCE

The development version is on github at http://github.com/madsen/pod-weaver-section-allowoverride and may be cloned from git://github.com/madsen/pod-weaver-section-allowoverride.git

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Christopher J. Madsen.

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