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
    Bla

The 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 top3

DESCRIPTION

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_hash

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

SEE ALSO

Pod::Simple

Tie::File

cpanm Pod::Simple::Select

perl -MCPAN -e shell
install Pod::Simple::Select