Pod::Elemental::MakeSelector(3)

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

VERSION
This document describes version 0.12 of Pod::Elemental::MakeSelector, released October 17, 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. Instead, 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 =head2 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.