Pod::Weaver::Role::SectionReplacer - A Pod::Weaver section that will replace itself in the original document.
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
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
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:
[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.
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.
If your plugin wishes to implement a
transform_document() of its own, you will need to reconcile the two.
After installing, you can find documentation for this module with the perldoc command.
You can also look for information at:
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.