Enhance exact text replacement functionality in line_in_file

- Updated documentation to clarify that the `exact` action treats special characters (dots, brackets, parentheses, etc.) as literal characters, ensuring true literal matching.
- Added new functions `escape_sed_pattern` and `escape_sed_replacement` to properly escape special characters for use in sed, improving the reliability of text replacements in configuration files.

Author: jaydrogers

docs/content/docs/8.advanced/99.create-your-own-template.md

@@ -129,7 +129,7 @@ line_in_file [--file FILE] [--action ACTION] [ARGUMENTS...]
 | `ensure` | Ensures specified lines exist in the file. | One or more lines to ensure. | Appends the line(s) to the end of the file. |
 | `replace` | Replaces a line containing specific content with a new line. | Two arguments: search content and replacement line. | Appends the replacement line to the file. |
 | `after` | Inserts a new line after a line containing specific content. | Two arguments: search content and line to insert. | Appends both the search content and new line to the file. |
-| `exact` | Performs an exact replacement of text within the file. | Two arguments: exact text to replace and replacement text. | Returns an error. |
+| `exact` | Performs an exact replacement of text within the file. Special characters (dots, brackets, parentheses, etc.) are treated as literal characters. | Two arguments: exact text to replace and replacement text. | Returns an error. |
 | `search` | Searches for specified content in the file. | One argument: content to search for. | Returns false (exit code 1). |
 | `delete` | Deletes lines containing specified content. | One argument: content to delete. | Returns an error if the content is not found. |
 
@@ -169,6 +169,18 @@ label: Perform an exact text replacement
 line_in_file --file document.txt --action exact "old text" "new text"
 ```
 ::
+
+::code-panel
+---
+label: Replace text with special characters (dots, parentheses, etc.)
+---
+```bash
+# Works perfectly with special regex characters
+line_in_file --file docker-compose.yml --action exact \
+  "traefik.http.services.app.loadbalancer.server.port=8443" \
+  "traefik.http.services.app.loadbalancer.server.port=8080"
+```
+::
 ::code-panel
 ---
 label: Operate on multiple files
@@ -191,6 +203,7 @@ The function will output error messages to stderr and return a non-zero exit cod
 
 - The function uses `sed_inplace` for in-place file modifications. Ensure this function is available in your environment.
 - When using the `replace` action, forward slashes in the replacement string are automatically escaped.
+- When using the `exact` action, all regex special characters (dots, brackets, parentheses, etc.) are automatically escaped, ensuring true literal matching. This makes it perfect for replacing configuration values, URLs, or any text containing special characters.
 - The function creates the target file if it doesn't exist.
 
 ## Testing your template

lib/functions.sh

@@ -702,6 +702,18 @@ last_pull_timestamp() {
     grep "^$escaped_project_dir " "$cache_file" | awk '{print $2}'
 }
 
+escape_sed_pattern() {
+    # Escape special characters for use in sed search patterns
+    # This ensures exact string matching by escaping regex metacharacters
+    printf '%s' "$1" | sed 's/[][\.|$(){}?+*^/]/\\&/g'
+}
+
+escape_sed_replacement() {
+    # Escape special characters for use in sed replacement strings
+    # In replacement strings, we need to escape: \ / &
+    printf '%s' "$1" | sed 's/[\/&]/\\&/g' | sed 's/\\/\\\\/g'
+}
+
 line_in_file() {
     local action="ensure"
     local files=()
@@ -793,7 +805,12 @@ ${args[1]}" "$file"
                     return 1
                 fi
                 if grep -qF -- "${args[0]}" "$file"; then
-                    sed_inplace "s/${args[0]}/${args[1]}/g" "$file"
+                    # Escape special regex characters for exact matching
+                    local escaped_search
+                    local escaped_replace
+                    escaped_search=$(escape_sed_pattern "${args[0]}")
+                    escaped_replace=$(escape_sed_replacement "${args[1]}")
+                    sed_inplace "s/${escaped_search}/${escaped_replace}/g" "$file"
                 else
                     if [[ "$ignore_missing" == true ]]; then
                         return 0