view release on metacpan or  search on metacpan

lib/Pod/Stupid.pm  view on Meta::CPAN

    # Take care of any remaining text in the string
    my $last_pos  = pos( $text ) || 0;
    my $end_pos   = length( $text ) - 1;
    my $remainder = substr( $text, $last_pos );
    push @parsed_pieces, {
        non_pod   => 1,
        orig_txt  => $remainder,
        start_pos => $last_pos,
        end_pos   => $end_pos,
    } if $remainder;

    return \@parsed_pieces;
}



sub strip_string {
    my ( $self, $text_ref, $pod_pieces ) = @_;

    croak "missing \$text_ref parameter" unless defined $text_ref;

    # make a copy of the text if necessary.
    $text_ref = \"$text_ref" unless ref $text_ref;

    # get the pieces if we don't already have them
    $pod_pieces = $self->parse_string( $$text_ref ) unless ref $pod_pieces;

    my $shrinkage = 0;
    for my $pp ( @$pod_pieces ) {

        next unless $pp->{is_pod};

        my $length      = $pp->{end_pos}   - $pp->{start_pos};
        my $new_start   = $pp->{start_pos} - $shrinkage;
        substr( $$text_ref, $new_start, $length, '' );

        $shrinkage += $length;
    }
    return $$text_ref;
}

1 && q{Beauty is in the eye of the beholder}; # Truth.



=pod

=head1 NAME

Pod::Stupid - The simplest, stupidest 'pod parser' possible

=head1 VERSION

version 0.005

=head1 SYNOPSIS

  use Pod::Stupid;
  
  my $file = shift; # '/some/file/with/pod.pl';
  my $original_text = do { local( @ARGV, $/ ) = $file; <> }; # slurp
  
  my $ps = Pod::Stupid->new();
  
  # in scalar context returns an array of hashes.
  my $pieces = $ps->parse_string( $original_text );
  
  # get your text sans all POD
  my $stripped_text = $ps->strip_string( $original_text );
  
  # reconstruct the original text from the pieces...
  substr( $stripped_text, $_->{start_pos}, 0, $_->{orig_txt} )
      for grep { $_->{is_pod} } @$pieces;
  
  print $stripped_text eq $original_text ? "ok - $file\n" : "not ok - $file\n";

=head1 DESCRIPTION

This module was written to do one B<simple> thing: Given some text
as input, split it up into pieces of POD "paragraphs" and non-POD
"whatever" and output an AoH describing each piece found, in order.

The end user can do whatever s?he wishes with the output AoH. It is
trivially simple to reconstruct the input from the output, and
hopefully I've included enough information in the inner hashes that
one can easily perform just about any other manipulation desired.

=head1 INDESCRIPTION

There are a bunch of things this module will B<NOT> do:

=over 4

=item *

Create a "parse tree"

=item *

Pod validation (it either parses or not)

=item *

Pod cleanup

=item *

"Handle" encoded text (but it I<should> still parse)

=item *

Feed your cat

=back

However, it may make it easier to do any of the above, with a lot
less time and effort spent trying to grok many of the other POD
parsing solutions out there.

A particular design decision I've made is to avoid needing to save
any state. This means there's no need or advantage to instantiating