This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
move the implementation of %-, %+ into core
[perl5.git] / ext / Tie-Hash-NamedCapture / NamedCapture.pm
CommitLineData
8cf6f931 1use strict;
80305961 2package Tie::Hash::NamedCapture;
3195cf34 3
d88d17cb 4our $VERSION = "0.13";
44a2ac75
YO
5
6__END__
7
8=head1 NAME
9
80305961 10Tie::Hash::NamedCapture - Named regexp capture buffers
44a2ac75
YO
11
12=head1 SYNOPSIS
13
80305961 14 tie my %hash, "Tie::Hash::NamedCapture";
3195cf34 15 # %hash now behaves like %+
44a2ac75 16
28d8d7f4 17 tie my %hash, "Tie::Hash::NamedCapture", all => 1;
3195cf34 18 # %hash now access buffers from regexp in $qr like %-
44a2ac75
YO
19
20=head1 DESCRIPTION
21
3195cf34 22This module is used to implement the special hashes C<%+> and C<%->, but it
28d8d7f4 23can be used to tie other variables as you choose.
44a2ac75 24
3195cf34
RGS
25When the C<all> parameter is provided, then the tied hash elements will be
26array refs listing the contents of each capture buffer whose name is the
27same as the associated hash key. If none of these buffers were involved in
28the match, the contents of that array ref will be as many C<undef> values
29as there are capture buffers with that name. In other words, the tied hash
9f8c97d1 30will behave as C<%->.
44a2ac75 31
3195cf34
RGS
32When the C<all> parameter is omitted or false, then the tied hash elements
33will be the contents of the leftmost defined buffer with the name of the
9f8c97d1
RGS
34associated hash key. In other words, the tied hash will behave as
35C<%+>.
44a2ac75 36
3195cf34
RGS
37The keys of C<%->-like hashes correspond to all buffer names found in the
38regular expression; the keys of C<%+>-like hashes list only the names of
39buffers that have captured (and that are thus associated to defined values).
44a2ac75 40
d88d17cb
TC
41This implementation has been moved into the core executable, but you
42can still load this module for backward compatibility.
43
44a2ac75
YO
44=head1 SEE ALSO
45
192b9cd1
AB
46L<perlreapi>, L<re>, L<perlmodlib/Pragmatic Modules>, L<perlvar/"%+">,
47L<perlvar/"%-">.
44a2ac75
YO
48
49=cut