NAME
Pod::Simple::Select - Select parts in a file using pod directives
VERSION
Version 0.002
log4perl.appender.Screen=Log::Dispatch::Screen
log4perl.appender.Screen.stderr=0
log4perl.appender.Screen.Threshold=DEBUG
log4perl.appender.Screen.mode=append
log4perl.appender.Screen.layout=Log::Log4perl::Layout::PatternLayout
log4perl.appender.Screen.layout.ConversionPattern=%c{1}-%M{1} %m%n
);
Log::Log4perl->init( \$conf );SYNOPSIS
use Pod::Simple::Select;
my $p = Pod::Simple::Select->new;
$p->output_file("out");
$p->select(["head1" =>["Top1"=>["head2"=>["Top12"]]], "head2" =>["Function doit"], "head3"=>["Top3"]]);
$p->parse_file(ex.pod);Given that the ex.pod file is
=head1 NotFound
Bla
Bla
Bla
=head1 NotFound
Bla
Bla
Bla
=head1 Top1
Bla under top1
Bla2 under top1
Bla3 under top1
=head2 Top12
Bla under top12
Bla2 under top12
Bla3 under top12
=cut
code
code
code
=head2 Function C<Doit>
Bla under Function Doit
Bla2 under Function Doit
Bla3 under Function Doit
=head2 Top12
Bla under top12_2
Bla2 under top12_2
Bla3 under top12_2
=head1 NotFound
Bla
Bla
Bla
=head3 Top3
Bla under top3
=head1 NotFound
Bla
Bla
BlaThe out file will be
=head2 Top12
Bla under top12
Bla2 under top12
Bla3 under top12
=head2 Function C<Doit>
Bla under Function Doit
Bla2 under Function Doit
Bla3 under Function Doit
=head3 Top3
Bla under top3DESCRIPTION
This module will extract specified sections of pod documentation from a file. This ability is provided by the select method which arguments specify the set of POD sections to select for processing/printing.
SECTION SPECIFICATIONS
The argument to select may be given as a hash or an array refence. An array reference containing array refereces will restrict the text processed to only the desired set of sections, or subsections following a section.
Pod directive is head1, head2 and so on.
The formal syntax of a section specification is:
Ordered parsing
["Pod directive" =>["Text following the directive"=>["Pod directive 2"=>["Text2"]], "Text3], "Pod directive 3" => [Text4], ...]A list of token will be made using these array references and that list will be used for the parsing. A key (:text after a pod directive) not found in the file will stop the parser from searching further down. If an array references are enclosed within each other, the parsing will search for a sequence in the same order.
Unordered parsing
{"Pod directive" =>["Text following the directive", "Text2", "Text3], "Another pod directive => [Text4], ...}A list of token is constructed during the parsing, and all the Pod directive and key are on the same level. The order in the hash has no meaning. A pod directive or a key given in the hash and not found in the file won't stop the parsing.
select()
$parser->select(["head1"=>["select()", "output_hash"]]);
$parser->select({head1 =>["select()", "output_hash"]});The first call will search for the pod section in that order. The second call will catch the two section in any order.
$parser->select(["head1" => ["select()", ["head1"=>["output_hash()"]]]]);This will search for a <=head1 output_hash() > pod secttion following a =head1 select() section.
output_hash()
$parser->ouptut_hashCalling this method before calling $p-parse_file($filename)> will have parse_file return a the parsing in hash. The keys are the text after the pod directives (followed by a counter if the same text is met more than once.
output_file( $filename )
$parser->output_file("selected_pod.txt");Will write the file with the pod sections selected in the parsing.
parse_file( $file_to_parse )
$parser->parse_file("Select.pm");This method run the parsing. It as to be called after $p-select(...)> and C>$p->output_file(...)> or $p-output_hash()>.
BUGS
See support below.
SUPPORT
Any questions or problems can be posted to me (rappazf) on my gmail account.
AUTHOR
François Rappaz CPAN ID: RAPPAZF
COPYRIGHT
François Rappaz 2017 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.