This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
dmq points out that %+ and %- are not arrays. Fix the doc.
[perl5.git] / ext / re / lib / re / Tie / Hash / NamedCapture.pm
CommitLineData
44a2ac75 1package re::Tie::Hash::NamedCapture;
3195cf34 2
44a2ac75
YO
3use strict;
4use warnings;
3195cf34
RGS
5
6our $VERSION = "0.02";
7
66e6b4c5 8no re 'debug';
44a2ac75
YO
9use re qw(is_regexp
10 regname
11 regnames
12 regnames_count
13 regnames_iterinit
14 regnames_iternext);
15
16sub TIEHASH {
17 my $classname = shift;
18 my $hash = {@_};
19
20 if ($hash->{re} && !is_regexp($hash->{re})) {
21 die "'re' parameter to ",__PACKAGE__,"->TIEHASH must be a qr//"
22 }
23
24 return bless $hash, $classname;
25}
26
27sub FETCH {
28 return regname($_[1],$_[0]->{re},$_[0]->{all});
29}
30
31sub STORE {
32 require Carp;
3195cf34 33 Carp::croak("STORE forbidden: hashes tied to ",__PACKAGE__," are read-only.");
44a2ac75
YO
34}
35
36sub FIRSTKEY {
37 regnames_iterinit($_[0]->{re});
38 return $_[0]->NEXTKEY;
39}
40
41sub NEXTKEY {
42 return regnames_iternext($_[0]->{re},$_[0]->{all});
43}
44
45sub EXISTS {
46 return defined regname( $_[1], $_[0]->{re},$_[0]->{all});
47}
48
49sub DELETE {
50 require Carp;
3195cf34 51 Carp::croak("DELETE forbidden: hashes tied to ",__PACKAGE__," are read-only");
44a2ac75
YO
52}
53
54sub CLEAR {
55 require Carp;
3195cf34 56 Carp::croak("CLEAR forbidden: hashes tied to ",__PACKAGE__," are read-only");
44a2ac75
YO
57}
58
59sub SCALAR {
60 return scalar regnames($_[0]->{re},$_[0]->{all});
61}
62
631;
64
65__END__
66
67=head1 NAME
68
3195cf34 69re::Tie::Hash::NamedCapture - Named regexp capture buffers
44a2ac75
YO
70
71=head1 SYNOPSIS
72
3195cf34
RGS
73 tie my %hash, "re::Tie::Hash::NamedCapture";
74 # %hash now behaves like %+
44a2ac75 75
3195cf34
RGS
76 tie my %hash, "re::Tie::Hash::NamedCapture", re => $qr, all => 1;
77 # %hash now access buffers from regexp in $qr like %-
44a2ac75
YO
78
79=head1 DESCRIPTION
80
3195cf34
RGS
81This module is used to implement the special hashes C<%+> and C<%->, but it
82can be used independently.
83
84When the C<re> parameter is set to a C<qr//> expression, then the tied
85hash is bound to that particular regexp and will return the results of its
86last successful match. If the parameter is omitted, then the hash behaves
87just as C<$1> does by referencing the last successful match in the
88currently active dynamic scope.
44a2ac75 89
3195cf34
RGS
90When the C<all> parameter is provided, then the tied hash elements will be
91array refs listing the contents of each capture buffer whose name is the
92same as the associated hash key. If none of these buffers were involved in
93the match, the contents of that array ref will be as many C<undef> values
94as there are capture buffers with that name. In other words, the tied hash
9f8c97d1 95will behave as C<%->.
44a2ac75 96
3195cf34
RGS
97When the C<all> parameter is omitted or false, then the tied hash elements
98will be the contents of the leftmost defined buffer with the name of the
9f8c97d1
RGS
99associated hash key. In other words, the tied hash will behave as
100C<%+>.
44a2ac75 101
3195cf34
RGS
102The keys of C<%->-like hashes correspond to all buffer names found in the
103regular expression; the keys of C<%+>-like hashes list only the names of
104buffers that have captured (and that are thus associated to defined values).
44a2ac75
YO
105
106For instance:
107
108 my $qr = qr/(?<foo>bar)/;
3195cf34
RGS
109 if ( 'bar' =~ $qr ) {
110 tie my %hash, "re::Tie::Hash::NamedCapture", re => $qr;
111 print $+{foo}; # prints "bar"
112 print $hash{foo}; # prints "bar" too
113 if ( 'bar' =~ /bar/ ) {
44a2ac75 114 # last successful match is now different
3195cf34
RGS
115 print $+{foo}; # prints nothing (undef)
116 print $hash{foo}; # still prints "bar"
44a2ac75
YO
117 }
118 }
119
120=head1 SEE ALSO
121
3195cf34 122L<re>, L<perlmodlib/Pragmatic Modules>, L<perlvar/"%+">, L<perlvar/"%-">.
44a2ac75
YO
123
124=cut