Added documentation about regular expressions

Author: coordt

docsrc/reference/search-and-replace-config.md

@@ -2,6 +2,14 @@
 
 Bump-my-version uses a combination of [template strings](https://docs.python.org/3/library/string.html#format-string-syntax) using a [formatting context](formatting-context.md) and regular expressions to search the configured files for the old or current version and replace the text with the new version.
 
+Bump My Version falls back to using a simple string search if the search template is not a valid regular expression or if the `no-regex` flag is `True`. The search template is always rendered using the formatting context. The basic logic is:
+
+1. Escape the formatting context for use in a regular expression.
+2. Render the search string using the escaped formatting context.
+3. Attempt to compile the rendered search string as a regular expression.
+4. If the rendered search string is a valid regular expression, use it.
+5. If the rendered search string is _not_ a valid regular expression or the `no-regex` flag is `True`, use the search string rendered with the unescaped context.
+
 ## Using template strings
 
 Both the search and replace templates are rendered using the [formatting context](formatting-context.md). However, only the search template is also treated as a regular expression. The replacement fields available in the formatting context are enclosed in curly braces `{}`. 
@@ -54,3 +62,27 @@ Gets rendered to:
 ```
 
 This string is used as a regular expression pattern to search.
+
+## Regular expression special characters
+
+The `.`, `^`, `$`, `*`, `+`, `?`, `()`, `[]`, `{}`, `\`, `|` characters are special characters in regular expressions. If your search string contains these characters, you must escape them with a backslash (`\`) to treat them as literal characters or set the `no-regex` flag to `True`.
+
+For example, if you are looking for this string in a file:
+
+```text
+[Unreleased] 2023-07-17
+```
+
+and you use this search pattern:
+
+```text
+[Unreleased] \\d{{4}}-\\d{{2}}-\\d{{2}}
+```
+
+Bump My Version will not find the string. While the rendered regular expression `[Unreleased] \d{4}-\d{2}-\d{2}` is valid, it is not searching for the literal `[Unreleased]`. Instead, it matches a single character in the list `U`, `n`, `r`, `e`, `l`, `a`, `s`, `d`.
+
+You must escape the `[` and `]` to treat them as literal characters:
+
+```text
+\[Unreleased\] \\d{{4}}-\\d{{2}}-\\d{{2}}
+```

tests/test_files.py

@@ -419,6 +419,30 @@ def test_regex_search(tmp_path: Path) -> None:
     assert version_path.read_text() == f"Release {now} '1.2.4'"
 
 
+def test_regex_search_with_escaped_chars(tmp_path: Path) -> None:
+    """A search that uses special characters is not treated as a regex."""
+    # Arrange
+    version_path = tmp_path / "VERSION"
+    version_path.write_text("## [Release] 1.2.3 1234-56-78")
+
+    overrides = {
+        "current_version": "1.2.3",
+        "search": r"## \[Release\] {current_version} \d{{4}}-\d{{2}}-\d{{2}}",
+        "replace": r"## [Release] {new_version} {now:%Y-%m-%d}",
+        "files": [{"filename": str(version_path)}],
+    }
+    conf, version_config, current_version = get_config_data(overrides)
+    new_version = current_version.bump("patch", version_config.order)
+    cfg_files = [files.ConfiguredFile(file_cfg, version_config) for file_cfg in conf.files]
+
+    # Act
+    files.modify_files(cfg_files, current_version, new_version, get_context(conf))
+
+    # Assert
+    now = datetime.now().isoformat()[:10]
+    assert version_path.read_text() == f"## [Release] 1.2.4 {now}"
+
+
 def test_bad_regex_search(tmp_path: Path, caplog) -> None:
     """A search string not meant to be a regex is still found and replaced."""
     # Arrange