NAME

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

VERSION

This document describes version 0.02 of Pod::Elemental::MakeSelector, released July 20, 2012.

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

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.10.1 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) 2012 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