NAME

Pod::Elemental::MakeSelector - Build complex selectors as a single sub

VERSION

This document describes version 0.11 of Pod::Elemental::MakeSelector, released June 20, 2015.

SYNOPSIS

use Pod::Elemental::MakeSelector;

my $author_selector = make_selector(
  -command => 'head1',
  -content => qr/^AUTHORS?$/,
);

DESCRIPTION

The selectors provided by Pod::Elemental::Selectors are fairly limited, and there's no built-in way to combine them. For example, there's no simple way to generate a selector that matches a section with a specific name (a fairly common requirement).

This module exports a single subroutine: make_selector. It can handle everything that Pod::Elemental::Selectors can do, plus many things it can't. It also makes it easy to combine criteria. It compiles all the criteria you supply into a single coderef.

A selector is just a coderef that expects a single parameter: an object that does Pod::Elemental::Paragraph. It returns a true value if the paragraph meets the selector's criteria.

CRITERIA

Most criteria that accept a parameter accept a string, a regex, or an arrayref of strings and/or regexes. However, Pod::Elemental::MakeSelector does not use Perl's ~~ smartmatch operator because it is considered experimental. Instoad, a limited form of smartmatching is performed by the code generator. This means arrayrefs are iterated when the selector is compiled. Modifying the arrayref later will not affect the selector.

Optional parameters must not begin with -, or they will be treated as criteria instead. If you need an optional parameter that begins with -, put it inside an arrayref.

Simple Criteria

-blank, # isa Pod::Elemental::Element::Generic::Blank
-flat,  # does Pod::Elemental::Flat
-node,  # does Pod::Elemental::Node

Command Paragraphs

-command,           # does Pod::Elemental::Command
-command => 'head1',           # and is =head1
-command => qr/^head[23]/,     # and matches regex
-command => [qw(head1 head2)], # 1 element must match

Content

-content => 'AUTHOR',       # matches =head1 AUTHOR
-content => qr/^AUTHORS?$/, # or =head1 AUTHORS
-content => [qw(AUTHOR BUGS)], # 1 element must match

This criterion is normally used in conjunction with -command to select a section with a specific title.

Regions

-region, # isa Pod::Elemental::Element::Pod5::Region
-region => 'list',      # and format_name eq 'list'
-region => qr/^list$/i, # and format_name matches regex
-region => [qw(list group)], # 1 element must match
-podregion    => 'list',          # =for :list
-nonpodregion => 'Pod::Coverage', # =for Pod::Coverage

Regions are created with the =begin or =for commands. The -podregion and -nonpodregion criteria work exactly like -region, but they ensure that is_pod is either true or false, respectively.

Conjunctions

-and => [ ... ], # all criteria must be true
-or  => [ ... ], # at least one must be true

These take an arrayref of criteria, and combine them using the specified operator. Note that make_selector does -and by default; make_selector @criteria is equivalent to make_selector -and => \@criteria.

Custom Criteria

-code => sub { ... }, # test $_[0] any way you want
-code => $selector,   # also accepts another selector

SUBROUTINES

make_selector

$selector = make_selector( ... );

make_selector takes a list of criteria and returns a selector that tests whether a supplied paragraph matches all the criteria. It does not allow you to pass a paragraph to be checked immediately; if you want to do that, then call the selector yourself. i.e., these two lines are equivalent:

s_command(head1 => $para); # From Pod::Elemental::Selectors
make_selector(qw(-command head1))->($para);

SEE ALSO

Pod::Elemental::Selectors comes with Pod::Elemental, but is much more limited than this module.

DEPENDENCIES

Pod::Elemental::MakeSelector requires Pod::Elemental and Perl 5.8.0 or later.

BUGS

Please report any bugs or feature requests to bug-pod-elemental-makeselector@rt.cpan.org or through the web interface at: http://rt.cpan.org/Public/Dist/Display.html?Name=Pod-Elemental-MakeSelector

AUTHOR

Christopher J. Madsen <perl@cjmweb.net>

SOURCE

The development version is on github at http://github.com/madsen/pod-elemental-makeselector and may be cloned from git://github.com/madsen/pod-elemental-makeselector.git

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Christopher J. Madsen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Pod::Elemental::MakeSelector

perl -MCPAN -e shell
install Pod::Elemental::MakeSelector