Initial bulk commit for "Git on MSys"
[msysgit/historical-msysgit.git] / lib / perl5 / 5.6.1 / msys / re.pm
blob3f142d9de4852cd0a7329b93002d802de5351368
1 package re;
3 $VERSION = 0.02;
5 =head1 NAME
7 re - Perl pragma to alter regular expression behaviour
9 =head1 SYNOPSIS
11 use re 'taint';
12 ($x) = ($^X =~ /^(.*)$/s); # $x is tainted here
14 $pat = '(?{ $foo = 1 })';
15 use re 'eval';
16 /foo${pat}bar/; # won't fail (when not under -T switch)
19 no re 'taint'; # the default
20 ($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here
22 no re 'eval'; # the default
23 /foo${pat}bar/; # disallowed (with or without -T switch)
26 use re 'debug'; # NOT lexically scoped (as others are)
27 /^(.*)$/s; # output debugging info during
28 # compile and run time
30 use re 'debugcolor'; # same as 'debug', but with colored output
31 ...
33 (We use $^X in these examples because it's tainted by default.)
35 =head1 DESCRIPTION
37 When C<use re 'taint'> is in effect, and a tainted string is the target
38 of a regex, the regex memories (or values returned by the m// operator
39 in list context) are tainted. This feature is useful when regex operations
40 on tainted data aren't meant to extract safe substrings, but to perform
41 other transformations.
43 When C<use re 'eval'> is in effect, a regex is allowed to contain
44 C<(?{ ... })> zero-width assertions even if regular expression contains
45 variable interpolation. That is normally disallowed, since it is a
46 potential security risk. Note that this pragma is ignored when the regular
47 expression is obtained from tainted data, i.e. evaluation is always
48 disallowed with tainted regular expresssions. See L<perlre/(?{ code })>.
50 For the purpose of this pragma, interpolation of precompiled regular
51 expressions (i.e., the result of C<qr//>) is I<not> considered variable
52 interpolation. Thus:
54 /foo${pat}bar/
56 I<is> allowed if $pat is a precompiled regular expression, even
57 if $pat contains C<(?{ ... })> assertions.
59 When C<use re 'debug'> is in effect, perl emits debugging messages when
60 compiling and using regular expressions. The output is the same as that
61 obtained by running a C<-DDEBUGGING>-enabled perl interpreter with the
62 B<-Dr> switch. It may be quite voluminous depending on the complexity
63 of the match. Using C<debugcolor> instead of C<debug> enables a
64 form of output that can be used to get a colorful display on terminals
65 that understand termcap color sequences. Set C<$ENV{PERL_RE_TC}> to a
66 comma-separated list of C<termcap> properties to use for highlighting
67 strings on/off, pre-point part on/off.
68 See L<perldebug/"Debugging regular expressions"> for additional info.
70 The directive C<use re 'debug'> is I<not lexically scoped>, as the
71 other directives are. It has both compile-time and run-time effects.
73 See L<perlmodlib/Pragmatic Modules>.
75 =cut
77 # N.B. File::Basename contains a literal for 'taint' as a fallback. If
78 # taint is changed here, File::Basename must be updated as well.
79 my %bitmask = (
80 taint => 0x00100000,
81 eval => 0x00200000,
84 sub setcolor {
85 eval { # Ignore errors
86 require Term::Cap;
88 my $terminal = Tgetent Term::Cap ({OSPEED => 9600}); # Avoid warning.
89 my $props = $ENV{PERL_RE_TC} || 'md,me,so,se,us,ue';
90 my @props = split /,/, $props;
91 my $colors = join "\t", map {$terminal->Tputs($_,1)} @props;
93 $colors =~ s/\0//g;
94 $ENV{PERL_RE_COLORS} = $colors;
98 sub bits {
99 my $on = shift;
100 my $bits = 0;
101 unless(@_) {
102 require Carp;
103 Carp::carp("Useless use of \"re\" pragma");
105 foreach my $s (@_){
106 if ($s eq 'debug' or $s eq 'debugcolor') {
107 setcolor() if $s eq 'debugcolor';
108 require XSLoader;
109 XSLoader::load('re');
110 install() if $on;
111 uninstall() unless $on;
112 next;
114 $bits |= $bitmask{$s} || 0;
116 $bits;
119 sub import {
120 shift;
121 $^H |= bits(1,@_);
124 sub unimport {
125 shift;
126 $^H &= ~ bits(0,@_);