Pod::Elemental::Selectors - predicates for selecting elements

Author

       Ricardo SIGNES <cpan@semiotic.systems>

Copyright And License

       This software is copyright (c) 2022 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.36.0                                       2023-01-05                     Pod::Elemental::Selectors(3pm)

Name

       Pod::Elemental::Selectors - predicates for selecting elements

Overview

       Pod::Elemental::Selectors provides a number of routines to check for Pod::Elemental paragraphs with given
       qualities.

Perl Version

       This library should run on perls released even a long time ago.  It should work on any version of perl
       released in the last five years.

       Although it may work on older versions of perl, no guarantee is made that the minimum required version
       will not be increased.  The version may be increased for any reason, and there is no promise that patches
       will be accepted to lower the minimum required perl.

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.