diff options
| -rw-r--r-- | ext/re/lib/re/Tie/Hash/NamedCapture.pm | 70 | ||||
| -rw-r--r-- | pod/perlvar.pod | 45 |
2 files changed, 69 insertions, 46 deletions
diff --git a/ext/re/lib/re/Tie/Hash/NamedCapture.pm b/ext/re/lib/re/Tie/Hash/NamedCapture.pm index b86463dfe8..7363491f94 100644 --- a/ext/re/lib/re/Tie/Hash/NamedCapture.pm +++ b/ext/re/lib/re/Tie/Hash/NamedCapture.pm @@ -1,7 +1,10 @@ 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 @@ -27,7 +30,7 @@ sub FETCH { 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 { @@ -45,12 +48,12 @@ sub EXISTS { 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 { @@ -63,50 +66,59 @@ __END__ =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 diff --git a/pod/perlvar.pod b/pod/perlvar.pod index fc738a0903..563a59951d 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -344,17 +344,20 @@ Similar to C<@+>, the C<%+> hash allows access to the named capture 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) @@ -615,16 +618,20 @@ After a match against some variable $var: =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"; } @@ -638,12 +645,16 @@ would print out: $-{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) |