NAME

Pod::Weaver::Role::SectionReplacer - a Pod::Weaver section that will replace itself in the original document.

VERSION

version 0.99_01

SYNOPSIS

A role for Pod::Weaver plugins, allowing them to replace a named section of the input document rather than appending a potentially duplicate section.

IMPLEMENTING

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:

  $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.

REQUIRED METHODS

$plugin->default_section_name()

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:

  $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

OPTIONAL METHODS

$plugin->default_section_aliases

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

INTERNAL METHODS

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.

$plugin->mvp_aliases()

Tells Config::MVP that section_alias is a synonym for section_aliases in the weaver.ini for plugins that use this role.

$plugin->mvp_multivalue_args()

Tells Config::MVP> that section_aliases always takes multiple-values and should be stored as an arrayref.

$plugin->transform_document()

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.

SUPPORT AND DOCUMENTATION

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:

RT, CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Pod-Weaver-Role-SectionReplacer

AnnoCPAN, Annotated CPAN documentation

http://annocpan.org/dist/Pod-Weaver-Role-SectionReplacer

CPAN Ratings

http://cpanratings.perl.org/d/Pod-Weaver-Role-SectionReplacer

Search CPAN

http://search.cpan.org/dist/Pod-Weaver-Role-SectionReplacer/

AUTHOR

Sam Graham <libpod-weaver-role-sectionreplacer-perl BLAHBLAH illusori.co.uk>

COPYRIGHT AND LICENSE

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.