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.

Most criteria that accept a parameter test it using smart matching, which means that they accept a string, a regex, or an arrayref of strings and/or regexes. (This also means that Perl 5.10.1 is required to use Pod::Elemental::MakeSelector.)

Optional parameters must not begin with -, or they will be treated as criteria instead.

-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.

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: