From 06b1edb68f251558601bf68d47e6bbde693089c9 Mon Sep 17 00:00:00 2001
From: Milos Djermanovic <milos.djermanovic@gmail.com>
Date: Fri, 29 Apr 2022 02:48:45 +0200
Subject: [PATCH] docs: clarify no-control-regex rule (#15808)

* docs: clarify no-control-regex rule

Fixes #15653

* fix escaped
---
 docs/src/rules/no-control-regex.md | 41 ++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 5 deletions(-)

diff --git a/docs/src/rules/no-control-regex.md b/docs/src/rules/no-control-regex.md
index feebe466189..542e8f39153 100644
--- a/docs/src/rules/no-control-regex.md
+++ b/docs/src/rules/no-control-regex.md
@@ -9,19 +9,31 @@ rule_type: problem
 
 Disallows control characters in regular expressions.
 
-Control characters are special, invisible characters in the ASCII range 0-31. These characters are rarely used in JavaScript strings so a regular expression containing these characters is most likely a mistake.
+Control characters are special, invisible characters in the ASCII range 0-31. These characters are rarely used in JavaScript strings so a regular expression containing elements that explicitly match these characters is most likely a mistake.
 
 ## Rule Details
 
-This rule disallows control characters in regular expressions.
+This rule disallows control characters and some escape sequences that match control characters in regular expressions.
+
+The following elements of regular expression patterns are considered possible errors in typing and are therefore disallowed by this rule:
+
+* Hexadecimal character escapes from `\x00` to `\x1F`.
+* Unicode character escapes from `\u0000` to `\u001F`.
+* Unescaped raw characters from U+0000 to U+001F.
+
+Control escapes such as `\t` and `\n` are allowed by this rule.
 
 Examples of **incorrect** code for this rule:
 
 ```js
 /*eslint no-control-regex: "error"*/
 
-var pattern1 = /\x1f/;
-var pattern2 = new RegExp("\x1f");
+var pattern1 = /\x00/;
+var pattern2 = /\x0C/;
+var pattern3 = /\x1F/;
+var pattern4 = /\u000C/;
+var pattern5 = new RegExp("\x0C"); // raw U+000C character in the pattern
+var pattern6 = new RegExp("\\x0C"); // \x0C pattern
 ```
 
 Examples of **correct** code for this rule:
@@ -30,9 +42,28 @@ Examples of **correct** code for this rule:
 /*eslint no-control-regex: "error"*/
 
 var pattern1 = /\x20/;
-var pattern2 = new RegExp("\x20");
+var pattern2 = /\u0020/;
+var pattern3 = /\t/;
+var pattern4 = /\n/;
+var pattern5 = new RegExp("\x20");
+var pattern6 = new RegExp("\\t");
+var pattern7 = new RegExp("\\n");
+```
+
+## Known Limitations
+
+When checking `RegExp` constructor calls, this rule examines evaluated regular expression patterns. Therefore, although this rule intends to allow syntax such as `\t`, it doesn't allow `new RegExp("\t")` since the evaluated pattern (string value of `"\t"`) contains a raw control character (the TAB character).
+
+```js
+/*eslint no-control-regex: "error"*/
+
+new RegExp("\t"); // disallowed since the pattern is: <TAB>
+
+new RegExp("\\t"); // allowed since the pattern is: \t
 ```
 
+There is no difference in behavior between `new RegExp("\t")` and `new RegExp("\\t")`, and the intention to match the TAB character is clear in both cases. They are equally valid for the purpose of this rule, but it only allows `new RegExp("\\t")`.
+
 ## When Not To Use It
 
 If you need to use control character pattern matching, then you should turn this rule off.