Add control token for control character escapes

Author: hlysine

src/expression.ts

@@ -17,6 +17,7 @@ import {
   bindAsIncomplete,
   captureName,
   compareCodePoint,
+  controlChar,
   escapeForCharClass,
   flagString,
   getLiteralString,
@@ -273,6 +274,15 @@ class RegExpBuilder implements RegExpToken {
     return bindAsIncomplete(func, this, 'unicode');
   }
 
+  public get control(): RegExpToken['control'] {
+    function func(this: RegExpBuilder, ...args: RegExpLiteral): RegExpToken {
+      const literal = getLiteralString(args, false);
+      if (!controlChar.test(literal)) throw new Error('Invalid control character');
+      return this.addNode(`\\c${literal}`);
+    }
+    return bindAsIncomplete(func, this, 'control');
+  }
+
   public get charIn(): RegExpToken['charIn'] {
     function func(
       this: RegExpBuilder,
@@ -1244,6 +1254,34 @@ export const hex = r.hex;
  */
 export const unicode = r.unicode;
 
+/**
+ * Match a control character with value equal to the given letter's character value modulo 32.
+ * Only a letter from `a` to `z` or `A` to `Z` is allowed.
+ *
+ * For example, `\cJ` represents line break (`\n`), because the code point of `J` is 74, and 74 modulo 32 is 10,
+ * which is the code point of line break. Because an uppercase letter and its lowercase form differ by 32,
+ * `\cJ` and `\cj` are equivalent. You can represent control characters from 1 to 26 in this form.
+ *
+ * ( https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Character_escape#description )
+ *
+ * @example
+ *
+ * ```js
+ * control`j`
+ * control('j')
+ * control`J`
+ * control('J')
+ * ```
+ *
+ * RegExp equivalent:
+ *
+ * ```js
+ * /\cj/
+ * /\cJ/
+ * ```
+ */
+export const control = r.control;
+
 /**
  * Match a character listed in the group. A hyphen denotes a range of characters, such as `a-z`.
  *

src/helper.ts

@@ -8,11 +8,13 @@ export const hexNumber = /^[0-9a-fA-F]+$/;
 
 export const octalNumber = /^[0-7]+$/;
 
+export const controlChar = /^[a-zA-Z]$/;
+
 // octal escape sequences are not matched here because they should be wrapped in a character class
-export const negatableCharLiteral = /^(?:\\u[0-9a-fA-F]{4}|\\x[0-9a-fA-F]{2})$/;
+export const negatableCharLiteral = /^(?:\\u[0-9a-fA-F]{4}|\\x[0-9a-fA-F]{2}|\\c[a-zA-Z])$/;
 
 // last option refers to octal character or capture group backreference
-export const charLiteral = /^(?:\\u[0-9a-fA-F]{4}|\\x[0-9a-fA-F]{2}|\\\d{1,3})$/;
+export const charLiteral = /^(?:\\u[0-9a-fA-F]{4}|\\x[0-9a-fA-F]{2}|\\c[a-zA-Z]|\\\d{1,3})$/;
 
 export const captureName = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 

src/types.ts

@@ -9,6 +9,41 @@ export interface LiteralFunction {
   (template: TemplateStringsArray, ...args: unknown[]): RegExpToken;
 }
 
+type Lowercase =
+  | 'a'
+  | 'b'
+  | 'c'
+  | 'd'
+  | 'e'
+  | 'f'
+  | 'g'
+  | 'h'
+  | 'i'
+  | 'j'
+  | 'k'
+  | 'l'
+  | 'm'
+  | 'n'
+  | 'o'
+  | 'p'
+  | 'q'
+  | 'r'
+  | 's'
+  | 't'
+  | 'u'
+  | 'v'
+  | 'w'
+  | 'x'
+  | 'y'
+  | 'z';
+
+type Alphabet = Lowercase | Uppercase<Lowercase>;
+
+export interface ControlFunction {
+  (literal: Alphabet): RegExpToken;
+  (template: TemplateStringsArray, ...args: unknown[]): RegExpToken;
+}
+
 /**
  * A function with flexible parameters and return type.
  * This is used by custom tokens.
@@ -777,6 +812,34 @@ export interface RegExpToken {
    */
   get unicode(): LiteralFunction & IncompleteToken;
 
+  /**
+   * Match a control character with value equal to the given letter's character value modulo 32.
+   * Only a letter from `a` to `z` or `A` to `Z` is allowed.
+   *
+   * For example, `\cJ` represents line break (`\n`), because the code point of `J` is 74, and 74 modulo 32 is 10,
+   * which is the code point of line break. Because an uppercase letter and its lowercase form differ by 32,
+   * `\cJ` and `\cj` are equivalent. You can represent control characters from 1 to 26 in this form.
+   *
+   * ( https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Character_escape#description )
+   *
+   * @example
+   *
+   * ```js
+   * control`j`
+   * control('j')
+   * control`J`
+   * control('J')
+   * ```
+   *
+   * RegExp equivalent:
+   *
+   * ```js
+   * /\cj/
+   * /\cJ/
+   * ```
+   */
+  get control(): ControlFunction & IncompleteToken;
+
   /**
    * Match a character listed in the group. A hyphen denotes a range of characters, such as `a-z`.
    *