re2js 1.3.3 → 1.4.0

package/README.md

@@ -337,17 +337,17 @@ Note that the replacement string can include references to capturing groups from
 
 Parameters:
 - `replacement (String)`: The string that replaces the substrings found. Capture groups and special characters in the replacement string have special behavior. For example:
-  - `$0` refers to the entire matched substring
-  - `$1, $2, ...` refer to the corresponding capture groups in the pattern
-  - `\$` inserts a literal `$`
-  - `${name}` can be used to reference named capture groups
-  - on invalid group - throw exception
-- `perlMode (Boolean)`: If set to `true`, the replacement follows Perl/JS's rules for replacement. Defaults to `false`. If `perlMode = true`, changed rules for capture groups and special characters:
   - `$&` refers to the entire matched substring
   - `$1, $2, ...` refer to the corresponding capture groups in the pattern
   - `$$` inserts a literal `$`
   - `$<name>` can be used to reference named capture groups
   - on invalid group - ignore it
+- `javaMode (Boolean)`: If set to `true`, the replacement follows Java's rules for replacement. Defaults to `false`. If `javaMode = true`, changed rules for capture groups and special characters:
+  - `$0` refers to the entire matched substring
+  - `$1, $2, ...` refer to the corresponding capture groups in the pattern
+  - `\$` inserts a literal `$`
+  - `${name}` can be used to reference named capture groups
+  - on invalid group - throw exception
 
 Examples:
 
@@ -377,25 +377,28 @@ RE2JS.compile('(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)')
   .replaceFirst('$10$20') // 'jb0nopqrstuvwxyz123'
 ```
 
-Function support second argument `perlMode`, which work in the same way, as for `replaceAll` function
+Function support second argument `javaMode`, which work in the same way, as for `replaceAll` function
 
-### Translating Regular Expressions
+### Safe Replacements
 
-The `translateRegExp()` method preprocesses a given regular expression string to ensure compatibility with RE2JS.
-It applies necessary transformations, such as escaping special characters, adjusting Unicode sequences, and converting named capture groups
+When using untrusted user input as a replacement string, you must escape special characters so they aren't accidentally evaluated as capture groups (e.g., `$1`).
+
+Use the static method `quoteReplacement(string, javaMode)` to safely escape these characters. **Note:** You must pass the same `javaMode` boolean to `quoteReplacement` that you plan to use in `replaceAll()` / `replaceFirst()`, because the two modes use different escaping logic
 
 ```js
 import { RE2JS } from 're2js'
 
-const regexp = RE2JS.translateRegExp('(?<word>\\w+)') // '(?P<word>\\w+)'
-
-RE2JS.matches(regexp, 'hello') // true
-RE2JS.matches(regexp, '123') // true
+const text = 'The cost is 100 bucks.'
+const regex = RE2JS.compile('100 bucks')
+const unsafeUserInput = '$500'
 
-const unicodeRegexp = RE2JS.translateRegExp('\\u{1F600}') // '\\x{1F600}'
+// Safe (Default Mode)
+const safeDefault = RE2JS.quoteReplacement(unsafeUserInput) // "\$500"
+regex.matcher(text).replaceAll(safeDefault) // "The cost is $500."
 
-RE2JS.matches(unicodeRegexp, '😀') // true
-RE2JS.matches(unicodeRegexp, '😃') // false
+// Safe (Java Mode)
+const safeJava = RE2JS.quoteReplacement(unsafeUserInput, true) // "$$500"
+regex.matcher(text).replaceAll(safeJava, true) // "The cost is $500."
 ```
 
 ### Escaping Special Characters
@@ -423,6 +426,25 @@ console.log(RE2JS.compile('a+b').programSize()); // Outputs: 5
 console.log(RE2JS.compile('(a+b?)').programSize()); // Outputs: 8
 ```
 
+### Translating Regular Expressions
+
+The `translateRegExp()` method preprocesses a given regular expression string to ensure compatibility with RE2JS.
+It applies necessary transformations, such as escaping special characters, adjusting Unicode sequences, and converting named capture groups
+
+```js
+import { RE2JS } from 're2js'
+
+const regexp = RE2JS.translateRegExp('(?<word>\\w+)') // '(?P<word>\\w+)'
+
+RE2JS.matches(regexp, 'hello') // true
+RE2JS.matches(regexp, '123') // true
+
+const unicodeRegexp = RE2JS.translateRegExp('\\u{1F600}') // '\\x{1F600}'
+
+RE2JS.matches(unicodeRegexp, '😀') // true
+RE2JS.matches(unicodeRegexp, '😃') // false
+```
+
 ## Performance
 
 The RE2JS engine runs more slowly compared to native RegExp objects. This reduced speed is also noticeable when comparing RE2JS to the original RE2 engine. The C++ implementation of the RE2 engine includes both NFA (Nondeterministic Finite Automaton) and DFA (Deterministic Finite Automaton) engines, as well as a variety of optimizations. Russ Cox ported a simplified version of the NFA engine to Go. Later, Alan Donovan ported the NFA-based Go implementation to Java. I then ported the NFA-based Java implementation (plus Golang stuff, which are not present in Java implementation, like checks for regular expression complexity) to a pure JS version. This is another reason why the pure JS version will perform more slowly compared to the original RE2 engine.

package/build/index.cjs.cjs

@@ -2,7 +2,7 @@
  * re2js
  * RE2JS is the JavaScript port of RE2, a regular expression engine that provides linear time matching
  *
- * @version v1.3.3
+ * @version v1.4.0
  * @author Alexey Vasiliev
  * @homepage https://github.com/le0pard/re2js#readme
  * @repository github:le0pard/re2js
@@ -1126,16 +1126,31 @@ class Matcher {
    * {@link #appendReplacement} as a literal replacement of {@code s}.
    *
    * @param {string} str the string to be quoted
+   * @param {boolean} [javaMode=false] whether the replacement will be used in javaMode
    * @returns {string} the quoted string
    */
-  static quoteReplacement(str) {
-    if (str.indexOf('\\') < 0 && str.indexOf('$') < 0) {
+  static quoteReplacement(str, javaMode = false) {
+    if (javaMode) {
+      // Java mode escape '\' and '$' with a backslash
+      if (str.indexOf('\\') < 0 && str.indexOf('$') < 0) {
+        return str;
+      }
+      return str.split('').map(s => {
+        const c = s.codePointAt(0);
+        if (c === Codepoint.CODES.get('\\') || c === Codepoint.CODES.get('$')) {
+          return `\\${s}`;
+        }
+        return s;
+      }).join('');
+    }
+
+    // In JS mode, '\' is not a special character, but '$' must be escaped as '$$'
+    if (str.indexOf('$') < 0) {
       return str;
     }
     return str.split('').map(s => {
-      const c = s.codePointAt(0);
-      if (c === Codepoint.CODES.get('\\') || c === Codepoint.CODES.get('$')) {
-        return `\\${s}`;
+      if (s.codePointAt(0) === Codepoint.CODES.get('$')) {
+        return '$$';
       }
       return s;
     }).join('');
@@ -1425,13 +1440,13 @@ class Matcher {
    * earlier, escape the first digit that should not be used.
    *
    * @param {string} replacement the replacement string
-   * @param {boolean} [perlMode=false] activate perl/js mode (different behaviour for capture groups and special characters)
+   * @param {boolean} [javaMode=false] activate java mode (different behaviour for capture groups and special characters)
    * @returns {string}
    * @throws IllegalStateException if there was no most recent match
    * @throws IndexOutOfBoundsException if replacement refers to an invalid group
    * @private
    */
-  appendReplacement(replacement, perlMode = false) {
+  appendReplacement(replacement, javaMode = false) {
     let res = '';
     const s = this.start();
     const e = this.end();
@@ -1439,7 +1454,7 @@ class Matcher {
       res += this.substring(this.appendPos, s);
     }
     this.appendPos = e;
-    res += perlMode ? this.appendReplacementInternalPerl(replacement) : this.appendReplacementInternal(replacement);
+    res += javaMode ? this.appendReplacementInternalJava(replacement) : this.appendReplacementInternalJs(replacement);
     return res;
   }
 
@@ -1448,7 +1463,7 @@ class Matcher {
    * @returns {string}
    * @private
    */
-  appendReplacementInternal(replacement) {
+  appendReplacementInternalJava(replacement) {
     let res = '';
     let last = 0;
     const m = replacement.length;
@@ -1514,7 +1529,7 @@ class Matcher {
    * @returns {string}
    * @private
    */
-  appendReplacementInternalPerl(replacement) {
+  appendReplacementInternalJs(replacement) {
     let res = '';
     let last = 0;
     const m = replacement.length;
@@ -1611,12 +1626,12 @@ class Matcher {
    * {@code appendReplacement}.
    *
    * @param {string} replacement - the replacement string
-   * @param {boolean} [perlMode=false] - activate perl/js mode (different behaviour for capture groups and special characters)
+   * @param {boolean} [javaMode=false] - activate java mode (different behaviour for capture groups and special characters)
    * @returns {string} the input string with the matches replaced
-   * @throws IndexOutOfBoundsException if replacement refers to an invalid group and perlMode is false
+   * @throws IndexOutOfBoundsException if replacement refers to an invalid group and javaMode is true
    */
-  replaceAll(replacement, perlMode = false) {
-    return this.replace(replacement, true, perlMode);
+  replaceAll(replacement, javaMode = false) {
+    return this.replace(replacement, true, javaMode);
   }
 
   /**
@@ -1624,27 +1639,27 @@ class Matcher {
    * {@code appendReplacement}.
    *
    * @param {string} replacement - the replacement string
-   * @param {boolean} [perlMode=false] - activate perl/js mode (different behaviour for capture groups and special characters)
+   * @param {boolean} [javaMode=false] - activate java mode (different behaviour for capture groups and special characters)
    * @returns {string} the input string with the first match replaced
-   * @throws IndexOutOfBoundsException if replacement refers to an invalid group and perlMode is false
+   * @throws IndexOutOfBoundsException if replacement refers to an invalid group and javaMode is true
    */
-  replaceFirst(replacement, perlMode = false) {
-    return this.replace(replacement, false, perlMode);
+  replaceFirst(replacement, javaMode = false) {
+    return this.replace(replacement, false, javaMode);
   }
 
   /**
    * Helper: replaceAll/replaceFirst hybrid.
    * @param {string} replacement - the replacement string
    * @param {boolean} [all=true] - replace all matches
-   * @param {boolean} [perlMode=false] - activate perl/js mode (different behaviour for capture groups and special characters)
+   * @param {boolean} [javaMode=false] - activate java mode (different behaviour for capture groups and special characters)
    * @returns {string}
    * @private
    */
-  replace(replacement, all = true, perlMode = false) {
+  replace(replacement, all = true, javaMode = false) {
     let res = '';
     this.reset();
     while (this.find()) {
-      res += this.appendReplacement(replacement, perlMode);
+      res += this.appendReplacement(replacement, javaMode);
       if (!all) {
         break;
       }
@@ -6201,6 +6216,20 @@ class RE2JS {
     return Utils.quoteMeta(str);
   }
 
+  /**
+   * Quotes '\' and '$' in {@code str}, so that the returned string could be used in
+   * replacement methods as a literal replacement of {@code str}.
+   *
+   * This is a convenience delegation to {@link Matcher.quoteReplacement}.
+   *
+   * @param {string} str the string to be quoted
+   * @param {boolean} [javaMode=false] whether the replacement will be used in javaMode
+   * @returns {string} the quoted string
+   */
+  static quoteReplacement(str, javaMode = false) {
+    return Matcher.quoteReplacement(str, javaMode);
+  }
+
   /**
    * Translates a given regular expression string to ensure compatibility with RE2JS.
    *