[FEATURE] %regex_sub built-in script function (#971)

This implements %regex_sub built-in function to enhance string-processing capabilities, allowing users to perform substitutes like:

- removing non-ascii characters
- replacing subsequent whitespace characters with a single whitespace

Thanks @tbabej !

docs/source/config_reference/scripting/scripting_functions.rst

@@ -560,6 +560,15 @@ regex_search
  the string as the first element of the Array. If there are capture groups, returns each
  group as a subsequent element in the Array.
 
+regex_sub
+~~~~~~~~~
+:spec: ``regex_sub(regex: String, replacement: String, string: String) -> String``
+
+:description:
+ Returns the string obtained by replacing the leftmost non-overlapping occurrences of the
+ pattern in string by the replacement string. The replacement string can reference the
+ match groups via backslash escapes. Callables as replacement argument are not supported.
+
 ----------------------------------------------------------------------------------------------------
 
 String Functions

src/ytdl_sub/script/functions/regex_functions.py

@@ -52,3 +52,13 @@ def regex_capture_groups(regex: String) -> Integer:
  Returns number of capture groups in regex
  """
  return Integer(re.compile(regex.value).groups)
+
+ @staticmethod
+ def regex_sub(regex: String, replacement: String, string: String) -> String:
+ """
+ :description:
+ Returns the string obtained by replacing the leftmost non-overlapping occurrences of the
+ pattern in string by the replacement string. The replacement string can reference the
+ match groups via backslash escapes. Callables as replacement argument are not supported.
+ """
+ return String(re.sub(regex.value, replacement.value, string.value))

tests/unit/script/functions/test_regex_functions.py

@@ -43,3 +43,19 @@ def test_regex_search(self, values: str, expected_output: str):
  def test_regex_fullmatch(self, values: str, expected_output: str):
  output = single_variable_output(f"{{%regex_fullmatch({values})}}")
  assert output == expected_output
+
+ @pytest.mark.parametrize(
+ "values, expected_output",
+ [
+ ("'[^A-Za-z0-9 ]', '', 'This title is AWESOME!!'", "This title is AWESOME"),
+ ("'\s+', '_', 'Consolidate spaces'", "Consolidate_spaces"),
+ (
+ "'(words) are (reordered)', '\\2 are \\1', 'Oh words are reordered'",
+ "Oh reordered are words",
+ ),
+ ("'MATCH', '', 'matcha is great'", "matcha is great"),
+ ],
+ )
+ def test_regex_sub(self, values: str, expected_output: str):
+ output = single_variable_output(f"{{%regex_sub({values})}}")
+ assert output == expected_output