Pod::Elemental::Selectors(3pm) User Contributed Perl Documentation Pod::Elemental::Selectors(3pm)NAME
Pod::Elemental::Selectors - predicates for selecting elements
VERSION
version 0.102362
OVERVIEW
Pod::Elemental::Selectors provides a number of routines to check for Pod::Elemental paragraphs with given qualities.
SELECTORS
Selectors are predicates: they examine paragraphs and return either true or false. All the selectors have (by default) names like:
"s_whatever". They expect zero or more parameters to affect the selection. If these parameters are given, but no paragraph, a callback
will be returned that will expect a paragraph. If a paragraph is given, the selector will return immediately.
For example, the "s_command" selector expects a parameter that can be the name of the command desired. Both of the following uses are
valid:
# create and use a callback:
my $selector = s_command('head1');
my @headers = grep { $selector->($_) } @paragraphs;
# just check a paragraph right now:
if ( s_command('head1', $paragraph) ) { ... }
The selectors can be imported individually or as the "-all" group, and can be renamed with Sub::Exporter features. (Selectors cannot yet
be curried by Sub::Exporter.)
s_blank
my $callback = s_blank;
if( s_blank($para) ) { ... }
"s_blank" tests whether a paragraph is a Generic::Blank element.
s_flat
my $callback = s_flat;
if( s_flat($para) ) { ... }
"s_flat" tests whether a paragraph does Pod::Elemental::Flat -- in other words, is content-only.
s_node
my $callback = s_node;
if( s_node($para) ) { ... }
"s_node" tests whether a paragraph does Pod::Elemental::Node -- in other words, whether it may have children.
s_command
my $callback = s_command;
my $callback = s_command( $command_name);
my $callback = s_command(@command_names);
if( s_command(undef, $para) ) { ... }
if( s_command( $command_name, $para) ) { ... }
if( s_command(@command_names, $para) ) { ... }
"s_command" tests whether a paragraph does Pod::Elemental::Command. If a command name (or a reference to an array of command names) is
given, the tested paragraph's command must match one of the given command names.
AUTHOR
Ricardo SIGNES <rjbs@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 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.
perl v5.14.2 2012-05-05 Pod::Elemental::Selectors(3pm)
Check Out this Related Man Page
Pod::Eventual(3pm) User Contributed Perl Documentation Pod::Eventual(3pm)NAME
Pod::Eventual - read a POD document as a series of trivial events
VERSION
version 0.093170
SYNOPSIS
package Your::Pod::Parser;
our $VERSION = '0.093170';
use base 'Pod::Eventual';
sub handle_event {
my ($self, $event) = @_;
print Dumper($event);
}
DESCRIPTION
POD is a pretty simple format to write, but it can be a big pain to deal with reading it and doing anything useful with it. Most existing
POD parsers care about semantics, like whether a "=item" occurred after an "=over" but before a "back", figuring out how to link a "L<>",
and other things like that.
Pod::Eventual is much less ambitious and much more stupid. Fortunately, stupid is often better. (That's what I keep telling myself,
anyway.)
Pod::Eventual reads line-based input and produces events describing each POD paragraph or directive it finds. Once complete events are
immediately passed to the "handle_event" method. This method should be implemented by Pod::Eventual subclasses. If it isn't,
Pod::Eventual's own "handle_event" will be called, and will raise an exception.
METHODS
read_handle
Pod::Eventual->read_handle($io_handle, \%arg);
This method iterates through the lines of a handle, producing events and calling the "handle_event" method.
The only valid argument in %arg (for now) is "in_pod", which indicates whether we should assume that we are parsing pod when we start
parsing the file. By default, this is false.
This is useful to behave differently when reading a .pm or .pod file.
read_file
This behaves just like "read_handle", but expects a filename rather than a handle.
read_string
This behaves just like "read_handle", but expects a string containing POD rather than a handle.
handle_event
This method is called each time Pod::Evental finishes scanning for a new POD event. It must be implemented by a subclass or it will raise
an exception.
handle_nonpod
This method is called each time a non-POD segment is seen -- that is, lines after "=cut" and before another command.
If unimplemented by a subclass, it does nothing by default.
handle_blank
This method is called at the end of a sequence of one or more blank lines.
If unimplemented by a subclass, it does nothing by default.
EVENTS
There are four kinds of events that Pod::Eventual will produce. All are represented as hash references.
Command Events
These events represent commands -- those things that start with an equals sign in the first column. Here are some examples of POD and the
event that would be produced.
A simple header:
=head1 NAME
{ type => 'command', command => 'head1', content => "NAME
", start_line => 4 }
Notice that the content includes the trailing newline. That's to maintain similarity with this possibly-surprising case:
=for HTML
We're actually still in the command event, here.
{
type => 'command',
command => 'for',
content => "HTML
We're actually still in the command event, here.
",
start_line => 8,
}
Pod::Eventual does not care what the command is. It doesn't keep track of what it's seen or whether you've used a command that isn't
defined. The only special case is "=cut", which is never more than one line.
=cut
We are no longer parsing POD when this line is read.
{
type => 'command',
command => 'cut',
content => "
",
start_line => 15,
}
Waiving this special case may be an option in the future.
Text Events
A text event is just a paragraph of text, beginning after one or more empty lines and running until the next empty line (or =cut). In Perl
5's standard usage of Pod, text content that begins with whitespace is a "verbatim" paragraph, and text content that begins with non-
whitespace is an "ordinary" paragraph.
Pod::Eventual doesn't care.
Text events look like this:
{
type => 'text',
content => "a string of text ending with a
",
start_line => 16,
}
Blank events
These events represent blank lines (or many blank lines) within a Pod section.
Blank events look like this:
{
type => 'blank',
content => "
",
start_line => 21,
}
Non-Pod events
These events represent non-Pod segments of the input.
Non-Pod events look like this:
{
type => 'nonpod',
content => "#!/usr/bin/perl
use strict;
use Acme::ProgressBar
",
start_line => 1,
}
AUTHOR
Ricardo SIGNES <rjbs@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2009 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.
perl v5.10.1 2009-11-13 Pod::Eventual(3pm)