/ 
DarkPAN-Utils-1.0.0
/ DarkPAN::Utils::Docs

NAME

DarkPAN::Utils::Docs - extract and render POD from Perl module source

SYNOPSIS

use DarkPAN::Utils::Docs;

# From a source string (e.g. extracted from a tarball)
my $docs = DarkPAN::Utils::Docs->new( text => $module_source );

if ( $docs->get_pod ) {
  print $docs->get_html;
}

# With a URL prefix for cross-references in the rendered HTML
my $docs = DarkPAN::Utils::Docs->new(
  text       => $module_source,
  url_prefix => 'https://cpan.openbedrock.net/orepan2/docs',
);

print $docs->get_html;

# From a filehandle
open my $fh, '<', 'lib/My/Module.pm' or die $!;
my $docs = DarkPAN::Utils::Docs->new( text => $fh );
print $docs->get_markdown;

# From a scalar reference
my $docs = DarkPAN::Utils::Docs->new( text => \$source_string );

# Convert a plain Markdown string to HTML without POD extraction
my $docs = DarkPAN::Utils::Docs->new( text => $readme_markdown );
my $html = $docs->to_html;

DESCRIPTION

DarkPAN::Utils::Docs accepts Perl module source (as a string, scalar reference, or filehandle) and extracts its embedded POD documentation using Pod::Extract. The extracted POD is converted to Markdown and then to HTML via Text::Markdown::Discount.

The constructor always calls parse_pod immediately, so all derived attributes (pod, code, sections, markdown, html) are populated by the time new returns.

The to_html method provides a lighter-weight alternative when the source text is already in Markdown format (e.g. a README.md) and POD extraction is not required.

CONSTRUCTOR

new

my $docs = DarkPAN::Utils::Docs->new( text => $source );

Creates a new instance. The text attribute is required. Immediately normalises the text and calls parse_pod, populating all derived attributes.

Attributes

text (required)

The source material to process. May be:

  • A plain string containing Perl source or Markdown.

  • A scalar reference (\$source) — dereferenced automatically.

  • An open filehandle — read completely and closed automatically.

url_prefix

Optional URL prefix prepended to cross-reference links in the rendered HTML. Passed directly to Pod::Extract and used to resolve Module::Name links into browsable URLs within the DarkPAN site.

pod

Populated by parse_pod. Contains the raw extracted POD text, or undef if no POD was found.

code

Populated by parse_pod. Contains the non-POD (code) portions of the source text.

sections

Populated by parse_pod. A data structure describing the top-level POD sections found in the source, as returned by Pod::Extract.

markdown

Populated by parse_pod. The POD rendered as a Markdown string.

html

Populated by parse_pod (and by to_html). The final HTML output rendered from the Markdown.

METHODS AND SUBROUTINES

parse_pod

$docs->parse_pod;

Extracts POD from the stored text, converts it to Markdown using Pod::Extract, and then renders the Markdown to HTML using Text::Markdown::Discount. Updates the pod, code, sections, markdown, and html attributes in place.

If no POD is found in the source, pod remains undef and html is not set.

Called automatically by new; callers do not normally need to invoke this directly unless the text attribute has been changed after construction.

Returns $self.

to_html

my $html = $docs->to_html;

my $html = $docs->to_html($markdown_string);

Converts Markdown to HTML using Text::Markdown::Discount. If a Markdown string is passed as an argument it is used directly. Otherwise the method falls back in order to: the stored markdown attribute, then the raw text attribute.

Returns undef if no usable content is found.

This method is intended for source text that is already in Markdown format (such as a README.md), where POD extraction via parse_pod is unnecessary.

Returns the rendered HTML string, and also sets the html attribute as a side effect.

AUTHOR

Rob Lauer - <rlauer@treasurersbriefcase.com>

SEE ALSO

DarkPAN::Utils, Pod::Extract, Text::Markdown::Discount, IO::Scalar

LICENSE

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