NAME

Pod::InComments - Perl extension for extracting POD documentation from comments in config file

SYNOPSIS

  use Pod::InComments;
  my $podparser = Pod::InComments->new( comment => ';' );
  $podparser->ParseFile( $my_config_file );
  $podparser->Pod2Hash();

  my $helptext = $podparser->Pod4Section( $section , $key );

DESCRIPTION

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

METHODS

new( comment => '#' )

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.

ParseFile( $config_file )

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.

Pod2Hash()

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.

Pod4Section( $section, $param )

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

then doing:

  my $pod = $podparser->Pod4Section( 'cpu', 'maxload' );
  will give you:

 The maxload setting gives an upperbound on how hard
 the CPU can be pushed.

SavePod( $file )

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.

GetPod()

Returns the entire POD formatted in text.

DisplayPod()

Prints the entire extracted POD documentation to STDOUT.

EXPORT

None by default.

AUTHOR

Jaap Voets, <narked@xperience-automatisering.nl>

COPYRIGHT AND LICENSE

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.