package re::Tie::Hash::NamedCapture;
+
use strict;
use warnings;
-our $VERSION = "0.01";
+
+our $VERSION = "0.02";
+
no re 'debug';
use re qw(is_regexp
regname
sub STORE {
require Carp;
- Carp::croak("STORE forbidden: Hashes tied to ",__PACKAGE__," are read/only.");
+ Carp::croak("STORE forbidden: hashes tied to ",__PACKAGE__," are read-only.");
}
sub FIRSTKEY {
sub DELETE {
require Carp;
- Carp::croak("DELETE forbidden: Hashes tied to ",__PACKAGE__," are read/only");
+ Carp::croak("DELETE forbidden: hashes tied to ",__PACKAGE__," are read-only");
}
sub CLEAR {
require Carp;
- Carp::croak("CLEAR forbidden: Hashes tied to ",__PACKAGE__," are read/only");
+ Carp::croak("CLEAR forbidden: hashes tied to ",__PACKAGE__," are read-only");
}
sub SCALAR {
=head1 NAME
-re::Tie::Hash::NamedCapture - Perl module to support named regex capture buffers
+re::Tie::Hash::NamedCapture - Named regexp capture buffers
=head1 SYNOPSIS
- tie my %hash,"re::Tie::Hash::NamedCapture";
- # %hash now behaves like %-
+ tie my %hash, "re::Tie::Hash::NamedCapture";
+ # %hash now behaves like %+
- tie my %hash,"re::Tie::Hash::NamedCapture",re => $qr, all=> 1,
- # %hash now access buffers from regex in $qr like %+
+ tie my %hash, "re::Tie::Hash::NamedCapture", re => $qr, all => 1;
+ # %hash now access buffers from regexp in $qr like %-
=head1 DESCRIPTION
-Implements the behaviour required for C<%+> and C<%-> but can be used
-independently.
+This module is used to implement the special hashes C<%+> and C<%->, but it
+can be used independently.
+
+When the C<re> parameter is set to a C<qr//> expression, then the tied
+hash is bound to that particular regexp and will return the results of its
+last successful match. If the parameter is omitted, then the hash behaves
+just as C<$1> does by referencing the last successful match in the
+currently active dynamic scope.
-When the C<re> parameter is provided, and the value is the result of
-a C<qr//> expression then the hash is bound to that particular regexp
-and will return the results of its last successful match. If the
-parameter is omitted then the hash behaves just as C<$1> does by
-referencing the last successful match.
+When the C<all> parameter is provided, then the tied hash elements will be
+array refs listing the contents of each capture buffer whose name is the
+same as the associated hash key. If none of these buffers were involved in
+the match, the contents of that array ref will be as many C<undef> values
+as there are capture buffers with that name. In other words, the tied hash
+will behave as the C<%-> array.
-When the C<all> parameter is provided then the result of a fetch
-is an array ref containing the contents of each buffer whose name
-was the same as the key used for the access. If the buffer wasn't
-involved in the match then an undef will be stored. When the all
-parameter is omitted or not a true value then the return will be
-a the content of the left most defined buffer with the given name.
-If there is no buffer with the desired name defined then C<undef>
-is returned.
+When the C<all> parameter is omitted or false, then the tied hash elements
+will be the contents of the leftmost defined buffer with the name of the
+associated hash key. In other words, the tied hash will behave as the
+C<%+> array.
+The keys of C<%->-like hashes correspond to all buffer names found in the
+regular expression; the keys of C<%+>-like hashes list only the names of
+buffers that have captured (and that are thus associated to defined values).
For instance:
my $qr = qr/(?<foo>bar)/;
- if ( 'bar' =~ /$qr/ ) {
- tie my %hash,"re::Tie::Hash::NamedCapture",re => $qr, all => 1;
- if ('bar'=~/bar/) {
+ if ( 'bar' =~ $qr ) {
+ tie my %hash, "re::Tie::Hash::NamedCapture", re => $qr;
+ print $+{foo}; # prints "bar"
+ print $hash{foo}; # prints "bar" too
+ if ( 'bar' =~ /bar/ ) {
# last successful match is now different
- print $hash{foo}; # prints foo
+ print $+{foo}; # prints nothing (undef)
+ print $hash{foo}; # still prints "bar"
}
}
=head1 SEE ALSO
-L<re>, L<perlmodlib/Pragmatic Modules>.
+L<re>, L<perlmodlib/Pragmatic Modules>, L<perlvar/"%+">, L<perlvar/"%-">.
=cut
buffers, should they exist, in the last successful match in the
currently active dynamic scope.
-C<$+{foo}> is equivalent to C<$1> after the following match:
+For example, C<$+{foo}> is equivalent to C<$1> after the following match:
- 'foo'=~/(?<foo>foo)/;
+ 'foo' =~ /(?<foo>foo)/;
-The underlying behaviour of %+ is provided by the L<re::Tie::Hash::NamedCapture>
-module.
+The keys of the C<%+> hash list only the names of buffers that have
+captured (and that are thus associated to defined values).
-B<Note:> As C<%-> and C<%+> are tied views into a common internal hash
+The underlying behaviour of C<%+> is provided by the
+L<re::Tie::Hash::NamedCapture> module.
+
+B<Note:> C<%-> and C<%+> are tied views into a common internal hash
associated with the last successful regular expression. Therefore mixing
iterative access to them via C<each> may have unpredictable results.
-Likewise, if the last successful match changes then the results may be
+Likewise, if the last successful match changes, then the results may be
surprising.
=item HANDLE->input_line_number(EXPR)
=item %-
X<%->
-Similar to %+, this variable allows access to the named capture
-buffers that were defined in the last successful match. It returns
-a reference to an array containing one value per buffer of a given
-name in the pattern.
+Similar to C<%+>, this variable allows access to the named capture buffers
+in the last successful match in the currently active dynamic scope. To
+each capture buffer name found in the regular expression, it associates a
+reference to an array containing the list of values captured by all
+buffers with that name (should there be several of them), in the order
+where they appear.
+
+Here's an example:
- if ('1234'
=~/(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) {
- foreach my $name (sort keys(%-)) {
- my $ary = $-{$name};
+ if ('1234'
=~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) {
+ foreach my $bufname (sort keys %-) {
+ my $ary = $-{$bufname};
foreach my $idx (0..$#$ary) {
- print "\$-{$name}[$idx] : ",
+ print "\$-{$bufname}[$idx] : ",
(defined($ary->[$idx]) ? "'$ary->[$idx]'" : "undef"),
"\n";
}
$-{B}[0] : '2'
$-{B}[1] : '4'
-The behaviour of %- is implemented via the L<re::Tie::Hash::NamedCapture> module.
+The keys of the C<%-> hash correspond to all buffer names found in
+the regular expression.
+
+The behaviour of C<%-> is implemented via the
+L<re::Tie::Hash::NamedCapture> module.
-Note that C<%-> and C<%+> are tied views into a common internal hash
+B<Note:> C<%-> and C<%+> are tied views into a common internal hash
associated with the last successful regular expression. Therefore mixing
iterative access to them via C<each> may have unpredictable results.
-Likewise, if the last successful match changes then the results may be
+Likewise, if the last successful match changes, then the results may be
surprising.
=item HANDLE->format_name(EXPR)
projects / platform / upstream / perl.git / commitdiff