ext/re/re.pm

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