NAME
Pod::Modifier - Add sections to an existing POD dynamically.
DESCRIPTION
Pod::Modifier allows adding to a Perl Modules' POD, dynamically, sections from POD of other Perl Modules. The alias (new 'head or header' to be given to) and index of appearance of these added sections can be changed as per provided APIs. Pod::Modifier by default would return a string of modified POD, which can then be parsed by a POD Parser of choice, optionally though, it can also act as a "POD to Usage", and it prints to the terminal using 'less' pager.
SYNOPSYS
Some basic usage of this module is presented through an example below, please check APIs and Pod::SectionToAdd for more advanced options.
Usage :
use Pod::Modifier;
# To get full path to current module
my $pkg = ref(__PACKAGE__);
$pkg =~ s/::/\//g;
$pkg .= ".pm";
my $pkg_fp = $INC{$pkg};
# Create modifier object
my $modifier = Pod::Modifier->new(PACKAGE=>"$pkg_fp");
# The following usage of addSection API will add a section 'OPTIONS' to the Pod of current file,
# and this new section is expected to be defined in list of files having their paths in array @bases.
# In the modified POD, this will be now at index '6', and aliased as 'GLOBAL OPTIONS'.
# That is, when the modified POD is printed, the section(s) 'OPTIONS' (combined if multiple files in @bases)
# will now show up as 6th section aliased as 'GLOBAL OPTIONS' in the new POD.
$modifier->addSection(SECTION=>"OPTIONS",SECTION_INDEX=>6,BASE=>\@bases,ALIAS=>"GLOBAL OPTIONS");
# To print the modified POD on pager as help, PAGE=>1 is used.
# The pager used is less, with -R option, Parser used is Pod::Perldoc::ToTerm
# To use own pod parser and pager, use without PAGE argument, or PAGE=>0, and process the returned Pod string.
$modifier->updatePod(PAGE=>1); # returns an undef with PAGE=>1
# To return it as string
my $pod_string = $modifier->updatePod();
APIs
new (PACKAGE="/path/to/CurrentPackage.pm")>
Class constructor.
addSection ( BASE = SCALAR|ARRAYREF SECTION => SCALAR SECTION_INDEX => SCALAR ALIAS => SCALAR (optional) )
Interface to add a section 'SECTION', defined in file(s) given by 'BASE', at index 'SECTION_INDEX', renamed in current Pod as 'ALIAS'.
updatePod(PAGE = (0|1))>
Update and return the modified POD string, which can be parsed using Pod parser of choice.
ARGUMENTS
new(PACKAGE=>'$package')
PACKAGE =>base-
SCALAR Path to the current file, to (the Pod of) which additinal sections are to be added.
addSection()
BASE =>base-
SCALAR The full path to perl module containing section to be added. Or, ARRAYREF list of full paths of perl modules containing required section.
SECTION =>section-
SCALAR Name of the head (1) section.
SECTION_INDEX =>index-
SCALAR Attribute to set position of insertion for this section.
ALIAS =>alias-
For multiple files, that is, where BASE is array reference, an alias can be used to rename the combined sections, using ALIAS.
updatePod(PAGE=>0|1)
PAGE =>0|1-
SCALAR Without an argument, or for PAGE=>0, the function will return the Pod as a string which can be parsed by parser of choice. For PAGE=>1, '/bin/less' is used for paging and Pod::Perldoc::ToTerm for parsing. The output is, thus, immediately paged to STDOUT in this case.
CAVEATS
While paging directly using this module, it is assumed the pager 'less' is available in system, which is then used with the -R option for constant repainting of terminal/ std output. For proper cross platform compatibility it is advised not to use this module for paging. Assumption is made that sections in modules would be starting as =head(n) and ending with =head(n) of the next section, or EOF, whichever first.
SUPPORT
This module is managed in a GitHub repository, https://github.com/codenho/PodModify Feel free to fork and contribute, or to clone and send patches!
Please use https://github.com/codenho/PodModify/issues/new to file a bug report.
More general questions or discussion about POD should be sent to the pod-people@perl.org mail list. Send an empty email to pod-people-subscribe@perl.org to subscribe.
AUTHOR
Udhav Verma <vermaudh@cpan.org>
LICENSE
Pod::Modifier (the distribution) is licensed under the same terms as Perl5.
ACKNOWLEDGMENTS
Bincy Sarah Thomas, for feedback and help in writing this module.