This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
remove compat3.sym and rename perld4.pod
[perl5.git] / ext / re / re.pm
CommitLineData
b3eb6a9b
GS
1package re;
2
56953603
IZ
3$VERSION = 0.02;
4
b3eb6a9b
GS
5=head1 NAME
6
7re - Perl pragma to alter regular expression behaviour
8
9=head1 SYNOPSIS
10
e4d48cc9
GS
11 use re 'taint';
12 ($x) = ($^X =~ /^(.*)$/s); # $x is tainted here
b3eb6a9b 13
2cd61cdb 14 $pat = '(?{ $foo = 1 })';
e4d48cc9 15 use re 'eval';
2cd61cdb 16 /foo${pat}bar/; # won't fail (when not under -T switch)
e4d48cc9
GS
17
18 {
19 no re 'taint'; # the default
20 ($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here
21
22 no re 'eval'; # the default
2cd61cdb 23 /foo${pat}bar/; # disallowed (with or without -T switch)
e4d48cc9 24 }
b3eb6a9b 25
0a92e3a8
GS
26 use re 'debug'; # NOT lexically scoped (as others are)
27 /^(.*)$/s; # output debugging info during
28 # compile and run time
2cd61cdb 29
3ffabb8c
GS
30(We use $^X in these examples because it's tainted by default.)
31
b3eb6a9b
GS
32=head1 DESCRIPTION
33
34When C<use re 'taint'> is in effect, and a tainted string is the target
35of a regex, the regex memories (or values returned by the m// operator
e4d48cc9
GS
36in list context) are tainted. This feature is useful when regex operations
37on tainted data aren't meant to extract safe substrings, but to perform
38other transformations.
b3eb6a9b 39
e4d48cc9 40When C<use re 'eval'> is in effect, a regex is allowed to contain
2cd61cdb
IZ
41C<(?{ ... })> zero-width assertions even if regular expression contains
42variable interpolation. That is normally disallowed, since it is a
43potential security risk. Note that this pragma is ignored when the regular
44expression is obtained from tainted data, i.e. evaluation is always
45disallowed with tainted regular expresssions. See L<perlre/(?{ code })>.
46
0a92e3a8
GS
47For the purpose of this pragma, interpolation of precompiled regular
48expressions (i.e., the result of C<qr//>) is I<not> considered variable
49interpolation. Thus:
2cd61cdb
IZ
50
51 /foo${pat}bar/
52
0a92e3a8 53I<is> allowed if $pat is a precompiled regular expression, even
2cd61cdb
IZ
54if $pat contains C<(?{ ... })> assertions.
55
56When C<use re 'debug'> is in effect, perl emits debugging messages when
57compiling and using regular expressions. The output is the same as that
58obtained by running a C<-DDEBUGGING>-enabled perl interpreter with the
59B<-Dr> switch. It may be quite voluminous depending on the complexity
60of the match.
61See L<perldebug/"Debugging regular expressions"> for additional info.
62
0a92e3a8
GS
63The directive C<use re 'debug'> is I<not lexically scoped>, as the
64other directives are. It has both compile-time and run-time effects.
b3eb6a9b
GS
65
66See L<perlmodlib/Pragmatic Modules>.
67
68=cut
69
70my %bitmask = (
e4d48cc9
GS
71taint => 0x00100000,
72eval => 0x00200000,
b3eb6a9b
GS
73);
74
75sub bits {
56953603 76 my $on = shift;
b3eb6a9b
GS
77 my $bits = 0;
78 unless(@_) {
79 require Carp;
80 Carp::carp("Useless use of \"re\" pragma");
81 }
56953603
IZ
82 foreach my $s (@_){
83 if ($s eq 'debug') {
8202fd39
G
84 require DynaLoader;
85 @ISA = ('DynaLoader');
86 bootstrap re;
56953603
IZ
87 install() if $on;
88 uninstall() unless $on;
89 next;
90 }
91 $bits |= $bitmask{$s} || 0;
92 }
b3eb6a9b
GS
93 $bits;
94}
95
96sub import {
97 shift;
56953603 98 $^H |= bits(1,@_);
b3eb6a9b
GS
99}
100
101sub unimport {
102 shift;
56953603 103 $^H &= ~ bits(0,@_);
b3eb6a9b
GS
104}
105
1061;