File Coverage

blib/lib/Pod/Weaver/Role/StringFromComment.pm

Criterion	Covered	Total	%
statement	18	18	100.0
branch	4	4	100.0
condition			n/a
subroutine	4	4	100.0
pod			n/a
total	26	26	100.0

package Pod::Weaver::Role::StringFromComment;
# ABSTRACT: Extract a string from a specially formatted comment
$Pod::Weaver::Role::StringFromComment::VERSION = '4.017';
use Moose::Role;
use namespace::autoclean;

#pod =head1 OVERVIEW
#pod
#pod This role assists L<Pod::Weaver sections|Pod::Weaver::Role::Section> by
#pod allowing them to pull strings from the source comments formatted like:
#pod
#pod     # KEYNAME: Some string...
#pod
#pod This is probably the most familiar to people using lines like the following to
#pod allow the L<Name section|Pod::Weaver::Section::Name> to determine a module's
#pod abstract:
#pod
#pod     # ABSTRACT: Provides the HypnoToad with mind-control powers
#pod
#pod It will extract these strings by inspecting the C<ppi_document> which
#pod must be given.
#pod
#pod =head1 PRIVATE METHODS
#pod
#pod This role supplies only methods meant to be used internally by its consumer.
#pod
#pod =head2 _extract_comment_content($ppi_doc, $key)
#pod
#pod Given a key, try to find a comment matching C<# $key:> in the C<$ppi_document>
#pod and return everything but the prefix.
#pod
#pod e.g., given a document with a comment in it of the form:
#pod
#pod     # ABSTRACT: Yada yada...
#pod
#pod ...and this is called...
#pod
#pod     $self->_extract_comment_content($ppi, 'ABSTRACT')
#pod
#pod ...it returns to us:
#pod
#pod     Yada yada...
#pod
#pod =cut

sub _extract_comment_content {
  my ($self, $ppi_document, $key) = @_;

  my $regex = qr/^\s*#+\s*$key:\s*(.+)$/m;

  my $content;
  my $finder = sub {
    my $node = $_[1];
    return 0 unless $node->isa('PPI::Token::Comment');
    if ( $node->content =~ $regex ) {
      $content = $1;
      return 1;
    }
    return 0;
  };

  $ppi_document->find_first($finder);

  return $content;
}

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Pod::Weaver::Role::StringFromComment - Extract a string from a specially formatted comment

=head1 VERSION

version 4.017

=head1 OVERVIEW

This role assists L<Pod::Weaver sections|Pod::Weaver::Role::Section> by
allowing them to pull strings from the source comments formatted like:

    # KEYNAME: Some string...

This is probably the most familiar to people using lines like the following to
allow the L<Name section|Pod::Weaver::Section::Name> to determine a module's
abstract:

    # ABSTRACT: Provides the HypnoToad with mind-control powers

It will extract these strings by inspecting the C<ppi_document> which
must be given.

=head1 PRIVATE METHODS

This role supplies only methods meant to be used internally by its consumer.

=head2 _extract_comment_content($ppi_doc, $key)

Given a key, try to find a comment matching C<# $key:> in the C<$ppi_document>
and return everything but the prefix.

e.g., given a document with a comment in it of the form:

    # ABSTRACT: Yada yada...

...and this is called...

    $self->_extract_comment_content($ppi, 'ABSTRACT')

...it returns to us:

    Yada yada...

=head1 AUTHOR

Ricardo SIGNES <[e-mail]>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by Ricardo SIGNES.

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

=cut