File Coverage

blib/lib/Weasel/FindExpanders.pm

Criterion	Covered	Total	%
statement	14	30	46.6
branch	1	8	12.5
condition	0	2	0.0
subroutine	5	6	83.3
pod	2	2	100.0
total	22	48	45.8

=head1 NAME

Weasel::FindExpanders - Mapping find patterns to xpath locators

=head1 VERSION

version 0.32

=head1 SYNOPSIS

  use Weasel::FindExpanders qw( register_find_expander );

  register_find_expander(
    'button',
    'HTML',
    sub {
       my %args = @_;
       $args{text} =~ s/'/''/g; # quote the quotes (XPath 2.0)
       return ".//button[text()='$args{text}']";
    });

  $session->find($session->page, "*button|{text=>\"whatever\"}");

=cut

=head1 DESCRIPTION

The concept of I<find expanders> is used to define XPath templates for use
with the C<find> and C<find_all> methods. Multiple patterns may be registered
with the same pattern name ("mnemonic"); eg, there could be a two patterns
associated with the C<button> mnemonic, one for the C<< <button> >> tag and
one for the C<< <input type="submit"> >> tag. Or there could even be more
patterns registered, eg., to match Vue, React or Web Component elements.
All patterns registered on a single mnemonic (template name) will be compiled
into a single XPath expression which will match any of the patterns.

Weasel comes with a standard set of patterns in the L<Weasel::FindExpanders::HTML>
package.

=cut

=head1 DEPENDENCIES



=cut

package Weasel::FindExpanders 0.32;

use strict;
use warnings;

use base 'Exporter';
use Carp;

our @EXPORT_OK = qw| register_find_expander expand_finder_pattern |;

=head1 SUBROUTINES/METHODS

=over

=item register_find_expander($pattern_name, $group_name, &expander_function)

Registers C<&expander_function> as an expander for C<$pattern_name> in
C<$group_name>.

C<Weasel::Session> selects the expanders to be applied using its C<groups>
attribute.

=cut


# Stores handlers as arrays per group
my %find_expanders;

sub register_find_expander {
    my ($pattern_name, $group, $expander_function) = @_;

    return push @{$find_expanders{$group}{$pattern_name}}, $expander_function;
}

=item expand_finder_pattern($pattern, $args, $groups)

Returns a string of concatenated (using xpath '|' operator) expansions.

When C<$groups> is undef, all groups will be searched for C<pattern_name>.

If the pattern doesn't match '*<pattern_name>|{<arguments>}', the pattern
is returned as the only list/arrayref element.

=cut

sub expand_finder_pattern {
    my ($pattern, $args, $groups) = @_;

    ##no critic(ProhibitCaptureWithoutTest)
    return $pattern
        if ! ($pattern =~ m/^\*([^\|]+)/x);
    my $name = $1;
    ##critic(ProhibitCaptureWithoutTest)

    croak "No expansions registered (while expanding '$pattern')"
        if scalar(keys %find_expanders) == 0;

    $groups //= [ keys %find_expanders ];   # undef --> unrestricted
    # Using eval below to transform a hash-in-string to a hash efficiently

    my @matches;

    for my $group (@{$groups}) {
        next if ! exists $find_expanders{$group}{$name};

        push @matches,
          reverse map { $_->(%{$args}) } @{$find_expanders{$group}{$name}};
    }

    croak "No expansions matching '$pattern'"
        if ! @matches;

    return join "\n|", @matches;
}

=back

=cut

=head1 AUTHOR

Erik Huelsmann

=head1 CONTRIBUTORS

Erik Huelsmann
Yves Lavoie

=head1 MAINTAINERS

Erik Huelsmann

=head1 BUGS AND LIMITATIONS

Bugs can be filed in the GitHub issue tracker for the Weasel project:
 https://github.com/perl-weasel/weasel/issues

=head1 SOURCE

The source code repository for Weasel is at
 https://github.com/perl-weasel/weasel

=head1 SUPPORT

Community support is available through
L<[e-mail]|mailto:[e-mail]>.

=head1 LICENSE AND COPYRIGHT

 (C) 2016-2023  Erik Huelsmann

Licensed under the same terms as Perl.

=cut


1;