Pod::InComments - Perl extension for extracting POD documentation from comments in config file
use Pod::InComments; my $podparser = Pod::InComments->new( comment => ';' ); $podparser->ParseFile( $my_config_file ); $podparser->Pod2Hash(); my $helptext = $podparser->Pod4Section( $section , $key );
This module was written to solve the problem of describing numerous parameters in a config file. When you add comments to the config file, it becomes a mess quickly. And no-one will take the time to properly read them. You can not add POD directly. So..... here is Pod::InComments.
It was developed when using Config::IniFiles format, so let's take that as the basis. The Config::IniFiles module let's you use config files in the form of the popular windows ini file. That is, they look like
[section] param1=some value param2 = another value param3=20.00 ; this is a comment [operating system] preferred=Linux using=Windows XP Pro
Constructor of the class. Specify the comment character(s) used in the config file. Defaults to ';'. You can use whatever you like here. So '####' is valid as well, but requires more typing in the config.
Parses the $config_file and extracts all the comment lines. The comment character(s) are stripped of each line. It returns a string with all the POD.
After parsing a config file, you will need to call this function to convert the POD into a hash. The keys of the hash are the head1 titles. If head2 elements are present, they will be subkeys of the hash.
Returns the POD belonging to the $section, or to $param of $section.
E.g., when your config file looks like:
;=head1 cpu ; ;Specifies cpu settings for normal boxes ;note that these will override factory settings! ; ;=head2 maxload ; ;The maxload setting gives an upperbound on how hard ;the CPU can be pushed. [cpu] maxload=4.0
my $pod = $podparser->Pod4Section( 'cpu', 'maxload' ); will give you: The maxload setting gives an upperbound on how hard the CPU can be pushed.
Saves the extracted pod to the $file. If you omit a file name, it will append '.pod' to the config file you parsed and saves to that file.
Returns the entire POD formatted in text.
Prints the entire extracted POD documentation to STDOUT.
None by default.
Jaap Voets, <firstname.lastname@example.org>
Copyright (C) 2007 by Jaap Voets
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.