view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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

VERSION
    version 0.005

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";

DESCRIPTION
    This module was written to do one 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.

INDESCRIPTION
    There are a bunch of things this module will NOT do:

    *   Create a "parse tree"

    *   Pod validation (it either parses or not)

    *   Pod cleanup

    *   "Handle" encoded text (but it *should* still parse)

    *   Feed your cat

    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 an
    object, except for your own preferences. You can use any method as
    either an object method or a class method and it will work the same way
    for both. This design should also discourage me from trying to bloat
    Pod::Stupid with every feature that tickles my fancy (or yours!) but
    still, I encourage any feature requests!

METHODS
  new
    the most basic object constructor possible. Currently takes no options
    because the object neither has nor needs to keep any state.

    This is only here if you want to use this module with an OO interface.

  parse_string
    Given a string, parses for pod and, in scalar context, returns an AoH
    describing each pod paragraph found, as well as any non-pod.