From: Rafael Garcia-Suarez <rgs@consttype.org>
Date: Mon, 3 May 2010 13:38:57 +0000 (+0200)
Subject: Reinstate some documentation about quotemeta
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=9702b155e486f017ed2d6a28ec16132482f38d90;p=p5sagit%2Fp5-mst-13.2.git

Reinstate some documentation about quotemeta

(that was removed in 8bdbc703cb0af3faf2163ebce618944c51f180a0)
---

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 8f1614f..5fe551f 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -4425,6 +4425,32 @@ the C<\Q> escape in double-quoted strings.
 
 If EXPR is omitted, uses C<$_>.
 
+quotemeta (and C<\Q> ... C<\E>) are useful when interpolating strings into
+regular expressions, because by default an interpolated variable will be
+considered a mini-regular expression. For example:
+
+    my $sentence = 'The quick brown fox jumped over the lazy dog';
+    my $substring = 'quick.*?fox';
+    $sentence =~ s{$substring}{big bad wolf};
+
+Will cause C<$sentence> to become C<'The big bad wolf jumped over...'>.
+
+On the other hand:
+
+    my $sentence = 'The quick brown fox jumped over the lazy dog';
+    my $substring = 'quick.*?fox';
+    $sentence =~ s{\Q$substring\E}{big bad wolf};
+
+Or:
+
+    my $sentence = 'The quick brown fox jumped over the lazy dog';
+    my $substring = 'quick.*?fox';
+    my $quoted_substring = quotemeta($substring);
+    $sentence =~ s{$quoted_substring}{big bad wolf};
+
+Will both leave the sentence as is. Normally, when accepting string input from
+the user, quotemeta() or C<\Q> must be used.
+
 =item rand EXPR
 X<rand> X<random>