/ 
Regexp-Exhaustive-0.01
River stage one • 1 direct dependent • 1 total dependent
/ Regexp::Exhaustive

NAME

Regexp::Exhaustive - Find all possible matches, including backtracked and overlapping, of a pattern against a string

SYNOPSIS

use Regexp::Exhaustive;

my @matches = Regexp::Exhaustive->new('abc' => qr/.+?/)->all;

my $matcher = Regexp::Exhaustive->new('abc' => qr/.+?/);
while (my ($match) = $matcher->next) {
    print "$match\n";
}

__END__
a
ab
abc
b
bc
c

DESCRIPTION

This module does an exhaustive match of a pattern against a string. That means that it will match all ways possible, including all backtracked and overlapping matches.

The main advantage this module provides is the iterator interface. It enables you to have arbitrary code between each match without loading every match into the memory first. The price you pay for this is efficiency, as the regex engine has to do extra work to resume the matching at the right place.

As a convenience the all method is provided. Currently it isn't just convenient though. It's also more efficient than iterating through the matches using next. This may change though.

This is an initial release, and many things may change for the next version. If you feel something is missing or poorly designed, now is the time to voice your opinion.

METHODS

For Regexp::Exhaustive

$matcher = Regexp::Exhaustive->new($str => qr/$pattern/)

new creates a new Regexp::Exhaustive object. The first argument is a string and the second is a qr// object.

Do not change the string while using this object or any associated match objects. Copy the string first if you plan to use. That's easily done by quoting it in the call:

my $matcher = Regexp::Exhaustive->new("$str" => qr/$pattern/);

Currently the behaviours of (?{}) and (??{}) assertions in a pattern given to Regexp::Exhaustive are undefined.

$clone = $matcher->clone

Creates a clone of $matcher. Note that $str still will be referenced.

$match = $matcher->next

Returns a match object for the next match. If there's no such match then undef is returned in scalar context and the empty list in list context.

@matches = $matcher->all

Generates and returns all matches in list context. Returns the number of matches in scalar context. This method may interfere with the next method, so if you mix next and all, call all on a clone:

my @matches = $matcher->clone->all;

For the match object

Match objects are overloaded to return the matched string (the value of method match).

$match->var('$SPECIAL_VARIABLE');

Returns the value of $SPECIAL_VARIABLE associated with the match. Arrays return their elements in list context and their sizes in scalar context. Supported variables:

Punctuation:    English:
$<*digits*>
$&              $MATCH
$`              $PREMATCH
$'              $POSTMATCH
$+              $LAST_PAREN_MATCH
$^N
@+              @LAST_MATCH_END
@-              @LAST_MATCH_START
$^R             $LAST_REGEXP_CODE_RESULT

Example:

my $str = 'asdf';
my $match = Regexp::Exhaustive::->new($str => qr/.(.)/)->next;

print $match->var('$1'), "\n";
print $match->var('$POSTMATCH'), "\n";
print join(' ', $match->var('@-')), "\n";

__END__
s
df
0 1
$match->prematch

Returns the equivalent of $`.

$match->match

Returns the equivalent of $&.

$match->postmatch

Returns the equivalent of $'.

$match->group($n)

Returns the $n:th capturing group. Equivalent to $<*digits*>. $n must be strictly positive.

$match->groups

Returns all capturing groups in list context. Returns the number of groups in scalar context.

$match->pos

Returns the equivalent of pos($str).

DIAGNOSTICS

The second argument to Regexp::Exhaustive->new() must be a Regexp (qr//) object

(F) Self-explanatory.

EXAMPLES

Finding all divisors

A commonly known snippet of regex can be used to find out if an integer is a prime number or not.

sub is_prime {
    my ($n) = @_;

    my $str = '.' x $n;

    return $str =~ /^(?:..+)\1+$/ ? 0 : 1;
}

print '9 is prime: ', is_prime(9), "\n";
print '11 is prime: ', is_prime(11), "\n";

__END__
9 is prime: 0
11 is prime: 1

Equally simple is it, with Regexp::Exhaustive, to find out not only if it's a prime number, but which its divisors are.

use Regexp::Exhaustive;

sub divisors {
    my ($i) = @_;

    return
        map length $_->group(1),
            Regexp::Exhaustive::
                ->new('.' x $i => qr/^(.+?)\1*$/)
                ->all
    ;
}

print "$_\n" for divisors(12);

__END__
1
2
3
4
6
12

Finding the cross product

Set::CrossProduct gives you the cross product of a set, and that's the good way of doing just that. But as an example, here's how you can find all possible combinations of two four-sided dice using Regexp::Exhaustive. To illustrate the difference between greedy and non-greedy matches I let the second die be in reversed order.

use Regexp::Exhaustive;

my $sides = '1234';
my $matcher = Regexp::Exhaustive::->new(
    "$sides\n$sides" => qr/^.*?(.).*\n.*(.)/
);

while (my ($match) = $matcher->next) {
    print $match->groups, "\n";
}

__END__
14
13
12
11
24
23
22
21
34
33
32
31
44
43
42
41

Finding all subsets

See "SYNOPSIS".

WARNING

This module uses the experimental (?{ code }) and (?(condition)yes-pattern|no-pattern)) assertions. Thus this module is as experimental as those assertions.

AUTHOR

Johan Lodin <lodin@cpan.org>

COPYRIGHT

Copyright 2005-2007 Johan Lodin. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

perlre for regular expressions.

perlvar for the special variables.