From f21e6780939bf9c46c67800fd955af3c476a729e Mon Sep 17 00:00:00 2001
From: trag1c <trag1cdev@yahoo.com>
Date: Fri, 27 Sep 2024 20:57:21 +0200
Subject: [PATCH] feat: add escape util (#41)

* refactor: loosen up _find_codes annotation

* feat: add escape util

* docs: mention escape util

* fix: add escape to `__all__`

* docs: fix bullet list rendering
---
 dahlia/__init__.py  |  3 ++-
 dahlia/utils.py     |  9 +++++++--
 docs/usage.md       | 14 +++++++++++---
 tests/test_utils.py | 16 +++++++++++++++-
 4 files changed, 35 insertions(+), 7 deletions(-)

diff --git a/dahlia/__init__.py b/dahlia/__init__.py
index 59ecaa2..154dbd1 100644
--- a/dahlia/__init__.py
+++ b/dahlia/__init__.py
@@ -1,9 +1,10 @@
 from dahlia.lib import Dahlia, Depth
-from dahlia.utils import clean, clean_ansi
+from dahlia.utils import clean, clean_ansi, escape
 
 __all__ = (
     "Dahlia",
     "Depth",
     "clean",
     "clean_ansi",
+    "escape",
 )
diff --git a/dahlia/utils.py b/dahlia/utils.py
index 4e4ae52..4ea80ab 100644
--- a/dahlia/utils.py
+++ b/dahlia/utils.py
@@ -11,7 +11,7 @@
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterable, Iterator
 
 
 def clean(string: str, marker: str = "&") -> str:
@@ -28,8 +28,13 @@ def clean_ansi(string: str) -> str:
     return string
 
 
+def escape(string: str, marker: str = "&") -> str:
+    """Escapes all instances of the marker in a string."""
+    return string.replace(marker, marker + "_")
+
+
 def _find_codes(
-    string: str, patterns: list[re.Pattern[str]]
+    string: str, patterns: Iterable[re.Pattern[str]]
 ) -> Iterator[tuple[str, bool | None, str]]:
     return reversed(
         dict.fromkeys(
diff --git a/docs/usage.md b/docs/usage.md
index 3bcd6da..0833b18 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -99,10 +99,14 @@ Dahlia(auto_reset=False).print("&ehi", "&othere")
 
 
 ## Cleaning utilities
-Dahlia provides two utility functions, `clean` and `clean_ansi`, for removing
-Dahlia and ANSI codes from strings, respectively.
+Dahlia provides three utility functions:
+
+* `clean` for removing Dahlia codes from strings
+* `clean_ansi` for removing ANSI codes from strings
+* `escape` for escaping Dahlia codes in strings
+
 ```py
-from dahlia import Dahlia, clean, clean_ansi
+from dahlia import Dahlia, clean, clean_ansi, escape
 
 dahlia = Dahlia()
 a = "&aa &b&lbunch &c&nof &d&ostyles &e&mhere"
@@ -114,6 +118,8 @@ print()
 print(repr(b))
 print(b)
 print(clean_ansi(b))
+print(escape(a))
+print(dahlia.convert(escape(a)))
 ```
 <div class="highlight"><pre><code>&aa &b&lbunch &c&nof &d&ostyles &e&mhere
 a bunch of styles here
@@ -121,6 +127,8 @@ a bunch of styles here
 '\x1b[38;2;85;255;85ma \x1b[38;2;85;255;255m\x1b[1mbunch \x1b[38;2;255;85;85m\x1b[4mof \x1b[38;2;255;85;255m\x1b[3mstyles \x1b[38;2;255;255;85m\x1b[9mhere\x1b[0m'
 <span class="dha">a </span><span class="dhl"><span class="dhb">bunch </span><span class="dhc"><span class="dhn">of </span></span><span class="dho"><span class="dhd"><span class="dhn">styles </span></span><span class="dhe"><span class="dhm"><span class="dhn">here</span></span></span></span></span>
 a bunch of styles here
+&_aa &_b&_lbunch &_c&_nof &_d&_ostyles &_e&_mhere
+&aa &b&lbunch &c&nof &d&ostyles &e&mhere
 </code></pre></div>
 
 [glossary]: https://github.com/dahlia-lib/spec/blob/main/SPECIFICATION.md#glossary
diff --git a/tests/test_utils.py b/tests/test_utils.py
index 1df09c0..114d64f 100644
--- a/tests/test_utils.py
+++ b/tests/test_utils.py
@@ -1,7 +1,7 @@
 import pytest
 
 from dahlia.__main__ import TEST_STRING
-from dahlia.utils import clean, clean_ansi
+from dahlia.utils import clean, clean_ansi, escape
 
 
 @pytest.mark.parametrize(
@@ -32,3 +32,17 @@ def test_clean_ansi(content: str, expected: str) -> None:
 
 def test_cli_test_string() -> None:
     assert clean(TEST_STRING) == "0123456789abcdefhijklmno"
+
+
+@pytest.mark.parametrize(
+    ("content", "marker", "expected"),
+    [
+        ("&e&nunderlined&rn yellow", "&", "&_e&_nunderlined&_rn yellow"),
+        ("&ame & &dher", "&", "&_ame &_ &_dher"),
+        ("&e&nunderlined&rn yellow", "!", "&e&nunderlined&rn yellow"),
+        ("!e!nunderlined!rn yellow", "!", "!_e!_nunderlined!_rn yellow"),
+        ("§_4 gives §4red", "§", "§__4 gives §_4red"),
+    ],
+)
+def test_escape(content: str, marker: str, expected: str) -> None:
+    assert escape(content, marker) == expected