view release on metacpan or  search on metacpan

lib/App/sdview/Parser/Pod.pm  view on Meta::CPAN

#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2021-2024 -- leonerd@leonerd.org.uk

use v5.26;
use warnings;

use Object::Pad 0.807;

package App::sdview::Parser::Pod 0.20;
class App::sdview::Parser::Pod :strict(params);

inherit Pod::Simple::Methody;

apply App::sdview::Parser;

use List::Keywords qw( any all );
use List::Util qw( min );

use String::Tagged;

use constant format => "Pod";
use constant sort_order => 10;

=head1 NAME

C<App::sdview::Parser::Pod> - parse Pod files for L<App::sdview>

=head1 SYNOPSIS

   $ sdview README.pod

   $ sdview -f Pod my-document

=head1 DESCRIPTION

This parser module adds to L<App::sdview> the ability to parse input text in
Pod formatting.

It uses L<Pod::Simple> as its driving parser.

The C<SE<lt>...E<gt>> formatting code is handled by converting inner spaces to
non-breaking spaces (U+00A0) characters in the returned string.

By default, verbatim blocks are scanned for likely patterns that indicate perl
code, and emitted with the C<language> field set to C<perl> if it looks
plausible. This can be overridden by embedded C<=code> or C<=for highlighter>
directives; see below.

=head2 Extensions

Partly as an experiment into how to handle possible future features of the Pod
spec, the following extensions are recognised:

=over 4

=item *

Inline formatting code C<UE<lt>...E<gt>> to request underline formatting.

=item *

C<=code> directive to set the highlighter language name for the next verbatim
paragraph.

=item *

Also follows the C<=for highlighter ...> spec used by
L<https://metacpan.org/pod/Pod::Simple::XHTML::WithHighlightConfig> for
setting the language name for following verbatim paragraphs.

=item *

Tables are I<partially> supported according to the suggestion given in
L<https://www.nntp.perl.org/group/perl.perl5.porters/2021/11/msg261904.html>,
within a section marked C<=begin table> or C<=begin table md>.

=item *

Tables are also partially supported by a format similar to mediawiki notation,
within a section marked C<=begin table mediawiki>.

=back

=cut

sub find_file ( $class, $name )
{
   # We could use `perldoc -l` but it's slow and noisy when it fails
   require Pod::Perldoc;
   my ( $found ) = Pod::Perldoc->new->searchfor( 0, $name, @INC );
   return $found;
}

sub can_parse_file ( $class, $file )
{
   return $file =~ m/\.pm$|\.pl$|\.pod$/;
}

ADJUST
{
   $self->accept_target( 'highlighter' );
   $self->accept_directive_as_data( 'code' );

   $self->accept_target( 'table' );
}