This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
applied patch, with tab tweak suggest by Peter Prymmer
[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
2cd61cdb
IZ
26 use re 'debug';
27 /^(.*)$/s; # output debugging info
28 # during compile and run time
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
47For the purpose of this pragma, interpolation of preexisting regular
48expressions is I<not> considered a variable interpolation, thus
49
50 /foo${pat}bar/
51
52I<is> allowed if $pat is a preexisting regular expressions, even
53if $pat contains C<(?{ ... })> assertions.
54
55When C<use re 'debug'> is in effect, perl emits debugging messages when
56compiling and using regular expressions. The output is the same as that
57obtained by running a C<-DDEBUGGING>-enabled perl interpreter with the
58B<-Dr> switch. It may be quite voluminous depending on the complexity
59of the match.
60See L<perldebug/"Debugging regular expressions"> for additional info.
61
62I<The directive C<use re 'debug'> is not lexically scoped.> It has
63both compile-time and run-time effects.
b3eb6a9b
GS
64
65See L<perlmodlib/Pragmatic Modules>.
66
67=cut
68
69my %bitmask = (
e4d48cc9
GS
70taint => 0x00100000,
71eval => 0x00200000,
b3eb6a9b
GS
72);
73
74sub bits {
56953603 75 my $on = shift;
b3eb6a9b
GS
76 my $bits = 0;
77 unless(@_) {
78 require Carp;
79 Carp::carp("Useless use of \"re\" pragma");
80 }
56953603
IZ
81 foreach my $s (@_){
82 if ($s eq 'debug') {
83 eval <<'EOE';
84 use DynaLoader;
85 @ISA = ('DynaLoader');
86 bootstrap re;
87EOE
88 install() if $on;
89 uninstall() unless $on;
90 next;
91 }
92 $bits |= $bitmask{$s} || 0;
93 }
b3eb6a9b
GS
94 $bits;
95}
96
97sub import {
98 shift;
56953603 99 $^H |= bits(1,@_);
b3eb6a9b
GS
100}
101
102sub unimport {
103 shift;
56953603 104 $^H &= ~ bits(0,@_);
b3eb6a9b
GS
105}
106
1071;