Pod::Weaver::Role::SectionReplacer - a Pod::Weaver section that will replace itself in the original document.
version 0.99_01
A role for Pod::Weaver plugins, allowing them to replace a named section of the input document rather than appending a potentially duplicate section.
This role is used by plugins that will find an existing section in the input document. It will prune the first existing section from the input document and make it available under original_section method:
original_section
$section_plugin->original_section();
The plugin could then choose to keep the original, by inserting it into the document again, or to write something new instead, or some combination of the two.
The plugin must provide a method, default_section_name which will return the default name of the section, as used in the =head1 line, this is available for later query via the section_name accessor:
default_section_name
section_name
$section_plugin->section_name
It is recommended that you use this accessor for generating the section title rather than hard-coding a value directly, because it then allows the end-user to configure the section name in their weaver.ini, eg:
[ReplaceLegal] section_name = MY CUSTOMIZED LICENSE AND COPYRIGHT HEADING
The plugin may also provide a default_section_aliases method, which should return an arrayref of alternative section names to match. Like section_name this allows the end-user to override the default section aliases:
default_section_aliases
[ReplaceLegal] section_name = MY CUSTOMIZED LICENSE AND COPYRIGHT HEADING section_alias = LICENSE AND COPYRIGHT section_alias = COPYRIGHT AND LICENSE section_alias = LICENCE AND COPYRIGHT section_alias = COPYRIGHT AND LICENCE
These methods are mostly internal to the role, but if you're also using them in your plugin, you will need reconcile the return values.
Tells Config::MVP that section_alias is a synonym for section_aliases in the weaver.ini for plugins that use this role.
section_alias
section_aliases
Tells Config::MVP> that section_aliases always takes multiple-values and should be stored as an arrayref.
Pod::Weaver:Role::SectionReplacer> implements the role Pod::Weaver::Role::Transformer>, and as such it provides its own $plugin->tranform_document() method in order to prune the original section from the input document before any further weaving is done.
$plugin->tranform_document()
If your plugin wishes to implement a transform_document() of its own, you will need to reconcile the two.
transform_document()
After installing, you can find documentation for this module with the perldoc command.
perldoc Pod::Weaver::Role::SectionReplacer
You can also look for information at:
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Pod-Weaver-Role-SectionReplacer
http://annocpan.org/dist/Pod-Weaver-Role-SectionReplacer
http://cpanratings.perl.org/d/Pod-Weaver-Role-SectionReplacer
http://search.cpan.org/dist/Pod-Weaver-Role-SectionReplacer/
Sam Graham <libpod-weaver-role-sectionreplacer-perl BLAHBLAH illusori.co.uk>
This software is copyright (c) 2010 by Sam Graham <libpod-weaver-role-sectionreplacer-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.
To install Pod::Weaver::Role::SectionReplacer, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::Weaver::Role::SectionReplacer
CPAN shell
perl -MCPAN -e shell install Pod::Weaver::Role::SectionReplacer
For more information on module installation, please visit the detailed CPAN module installation guide.