NAME

Pod::Headings -- extract headings and paragraphs (and other elements) from Pod

VERSION

version 0.03

SYNOPSIS

  my $p = Pod::Headings->new(
    head1 => sub ($parser, $elem, $attrs, $plaintext) {
        print " $elem: $plaintext\n";
        $parser->{_save_head1} = $plaintext;
        undef $parser->{_save_head2};
        $parser->{_save_first_para} = 1;
        1;
    },
    head2 => sub ($parser, $elem, $attrs, $plaintext) {
        print " $elem: $parser->{_save_head1}: $plaintext\n";
        $parser->{_save_head2} = $plaintext;
        $parser->{_save_first_para} = 1;
        1;
    },
    Para => sub ($parser, $elem, $attrs, $plaintext) {
        print " .... text: $plaintext\n" if $parser->{_save_first_para};
        $parser->{_save_first_para} = 0;
        1;
    },
    L => 1,  # Return 0 to drop the plaintext passed to the containing element
    }
  );

DESCRIPTION

This class is primarily of interest to persons wishing to extract headings from Pod, as when indexing the functions documented within a given Pod.

Call new() with a list of elements that your code will handle. Each element name should be followed either by a true/false value, or by a coderef which returns true/false. The truth value determines whether any plaintext contained in that element will be propagated to the containing element.

A supplied coderef will be called, at the end of handling the given element, with four arguments:

• A reference to the calling parser object

• The name of the element

• The attributes of the element (from its opening)

• The entire plaintext contained in the element

This is a subclass of Pod::Simple and inherits all its methods.

SEE ALSO

Pod::Simple

SUPPORT

This module is managed in an open GitHub repository, https://github.com/lindleyw/Pod-Definitions. Feel free to fork and contribute, or to clone and send patches.

AUTHOR

This module was written and is maintained by William Lindley <wlindley@cpan.org>.