NAME

CPANPLUS::Dist::Debora::Pod - Parse Pod documents

VERSION

version 0.012

SYNOPSIS

  use CPANPLUS::Dist::Debora::Pod;

  $pod = CPANPLUS::Dist::Debora::Pod->find($module_name, @dirs);

  $pod_text    = $pod->text;
  $summary     = $pod->summary;
  $description = $pod->description;

DESCRIPTION

This Pod::Simple subclass finds and parses files in Perl's Pod markup language. Information that is not relevant for extracting descriptions and license information is ignored.

SUBROUTINES/METHODS

find

  my $pod = CPANPLUS::Dist::Debora::Pod->find($module_name, @dirs);

Takes a module name and a list of directories to search for Pod files. Returns a Pod object or the undefined value.

new

  my $pod = CPANPLUS::Dist::Debora::Pod->new;

Creates a new object.

parse_file

  $pod->parse_file($name);

Parses the specified Pod file.

text

  my $pod_text = $pod->text;

Returns the Pod document, which is simplified for the purpose of finding descriptions and license information.

Use Software::LicenseUtils to guess the license.

  my @licenses = Software::LicenseUtils->guess_license_from_pod($pod_text);

title

  my $title = $pod->title;

Returns the Pod document's title or the undefined value.

If the Pod document contains the section below, "Hoo::Boy::Wowza - Stuff wow yeah!" will be returned.

  =head1 NAME

  Hoo::Boy::Wowza - Stuff wow yeah!

summary

  my $summary = $pod->summary;

Returns the Pod document's one-line description or the undefined value.

If the Pod document contains the section below, "Stuff wow yeah!" will be returned.

  =head1 NAME

  Hoo::Boy::Wowza - Stuff wow yeah!

description

  my $description = $pod->description;

Returns the first paragraphs of the Pod document's description or the undefined value.

copyrights

  for my $copyright (@{$pod->copyrights}) {
      my $year   = $copyright->{year};
      my $holder = $copyright->{holder};
  }

Returns the copyright years and holders.

section

  my $pod_text = $pod->section($level, $title);

Searches for a section with the specified title on the specified level.

DIAGNOSTICS

None.

CONFIGURATION AND ENVIRONMENT

None.

DEPENDENCIES

Requires the modules Pod::Simple and Pod::Simple::Search, which are distributed with Perl.

INCOMPATIBILITIES

None.

BUGS AND LIMITATIONS

None known.

AUTHOR

Andreas Vögele <voegelas@cpan.org>

LICENSE AND COPYRIGHT

Copyright (C) 2023 Andreas Vögele

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.