You want to use a literal string provided by a user or from some other source as part of a regular expression. However, you want to escape all regular expression metacharacters within the string before embedding it in your regex, to avoid any unintended consequences.

By adding a backslash before any characters that potentially have special meaning within a regular expression, you can safely use the resulting pattern to match a literal sequence of characters. Of the programming languages covered by this book, all except JavaScript have a built-in function or method to perform this task (listed in Table 5-3). However, for the sake of completeness, we’ll show how to pull this off using your own regex, even in the languages that have a ready-made solution.

[[]{}()*+?.\|^$-,&#s]

$&

$0

\$&

\$0

\

\&

\g<0>

RegExp.escape = function(str) {
    return str.replace(/[[]{}()*+?.\|^$-,&#s]/g, "\$&");
};

// Test it...
var str = "<Hello World.>";
var escapedStr = RegExp.escape(str);
alert(escapedStr == "<Hello\ World\.>"); // -> true

This recipe’s regular expression puts all the regex metacharacters inside a single character class. Let’s take a look at each of those characters, and examine why they need to be escaped. Some are less obvious than others:

The remaining characters matched by the regular expression are only special in special circumstances. They’re included in the list to err on the side of caution.

As for the replacement text, one of five tokens («$&», «&», «$0», «», or «g<0>») is used to restore the matched character along with a preceding backslash. In Perl, $& is actually a variable, and using it with any regular expression imposes a global performance penalty on all regular expressions. If $& is used elsewhere in your Perl program, it’s OK to use it as much as you want because you’ve already paid the price. Otherwise, it’s probably better to wrap the entire regex in a capturing group, and use $1 instead of $& in the replacement.

As explained in Block escape, you can create a block escape sequence within a regex using ‹Q⋯E›. However, block escapes are only supported by Java, PCRE, and Perl, and even in those languages block escapes are not foolproof. For complete safety, you’d still need to escape any occurrence of E within the string you plan to embed in your regex. In most cases it’s probably easier to just use the cross-language approach of escaping all regex metacharacters.

Recipe 2.1 discusses how to match literal characters and escape metacharacters. However, its list of characters that need to be escaped is shorter since it doesn’t concern itself with characters that may need to be escaped in free-spacing mode or when dropped into an arbitrary, longer pattern.

The example JavaScript solution in Recipe 5.2 creates a function that escapes any regular expression metacharacters within words to be searched for. It uses the shorter list of special characters from Recipe 2.1.

Techniques used in the regular expression and replacement text in this recipe are discussed in Chapter 2. Recipe 2.3 explains character classes. Recipe 2.20 explains how to insert the regex match into the replacement text.