This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add a usage scenario and common use pattern to perldoc -f quotemeta
authorShlomi Fish <shlomif@iglu.org.il>
Wed, 30 Dec 2009 11:18:23 +0000 (12:18 +0100)
committerAbigail <abigail@abigail.be>
Wed, 30 Dec 2009 11:18:23 +0000 (12:18 +0100)
pod/perlfunc.pod

index 25e28e1..114d4da 100644 (file)
@@ -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>