From: Shlomi Fish <shlomif@iglu.org.il>
Date: Wed, 30 Dec 2009 11:18:23 +0000 (+0100)
Subject: Add a usage scenario and common use pattern to perldoc -f quotemeta
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=c088ef569318bbdc082566d3567bbf231adc5267;p=p5sagit%2Fp5-mst-13.2.git

Add a usage scenario and common use pattern to perldoc -f quotemeta
---

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 25e28e1..114d4da 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -4328,6 +4328,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>