view release on metacpan or  search on metacpan

inc/Pod/Snippets.pm  view on Meta::CPAN

=head2 Snippet Syntax

B<Pod::Snippets> only deals with verbatim portions of the POD (that
is, as per L<perlpod>, paragraphs that start with whitespace at the
right) and custom markup starting with C<=for test>, C<=begin test> or
C<=end test>; it discards the rest (block text, actual Perl code,
character markup such as BE<lt>E<gt>, =head's and so on).  The keyword
"test" in C<=for test> and C<=begin test> can be replaced with
whatever one wants, using the C<-markup> argument to L</load>.
Actually the default value is not even "test"; nonetheless let's
assume you are using "test" yourself for the remainder of this
discussion.  The following metadata markup is recognized:

=over

=item B<=for test ignore>

Starts ignoring all POD whatsoever.  Verbatim portions of the POD are
no longer stashed by B<Pod::Snippets> until remanded by a subsequent
C<=for test>.

=item B<=for test>

Cancels the effect of an ongoing C<=for test ignore> directive.

=item B<=for test "foo" begin>

=item B<=for test "foo" end>

These signal the start and end of a I<named> POD snippet, that can
later be fetched by name using L</named>.  Unless countermanded by
appropriate parser options (see L</load>), named POD snippets can
nest freely (even badly).

=item B<=begin test>

=item B<=end test>

The POD between these markers will be seen by B<Pod::Snippets>, but
not by other POD formatters.  Otherwise has no effect on the naming or
ignoring of snippets; in particular, if the contents of the section is
not in POD verbatim style, it still gets ignored.

=item B<=begin test "foo">

=item B<=end test "foo">

These have the exact same effect as C<=for test "foo" begin> and
C<=for test "foo" end>, except that other POD formatters will not see
the contents of the block.

=back

=head1 CONSTRUCTORS

=head2 load ($source, -opt1 => $val1, ...)

Parses the POD from $source and returns an object of class
B<Pod::Snippets> that holds the snippets found therein.  $source may
be the name of a file, a file descriptor (glob reference) or any
object that has a I<getline> method.

Available named options are:

=over

=item B<< -filename => $filename >>

The value to set for L</filename>, that is, the name of the file to
use for C<#line> lines in L</as_code>.  The default behavior is to use
the filename passed as the $source argument, or if it was not a
filename, use the string "pod snippet" instead.

=item B<< -line => $line >>

The line number to start counting lines from, eg in case the $source
got a few lines chopped off it before being passed to I<load>.
Default is 1.

=item B<< -markup => $name >>

The markup (aka "format name" in L<perlpod>) to use as the first token
after C<=for>, C<=begin> or C<=end> to indicate that the directive is
to be processed by B<Pod::Snippets> (see L</Snippet Syntax>.  Default
is "Pod::Snippets".

=item B<< -report_errors => $sub >>

Invokes $sub like so to deal with warnings and errors:

  $sub->($severity, $text, $file, $line);

where $severity is either "WARNING" or "ERROR".  By default the
standard Perl L<perlfunc/warn> is used.

Regardless of the number of errors, the constructor tries to load the
whole file; see below.

=item B<< -named_snippets => "warn_impure" >>

Raises an error upon encountering this kind of construct:

=for metatests "named_snippets impure error" begin

  =for test "foobar" begin

     my $foobar = foobar();

  =head1 And now something completely different...

  =for test "foobar" end

=for metatests "named_snippets impure error" end

In other words, only verbatim blocks may intervene between the B<=for
test "foobar" begin> and B<=for test "foobar" end> markups.

=item B<< -named_snippets => "warn_multiple" >>

Raises a warning upon encountering this kind of construct: