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

@@ -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",
 )

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(

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,13 +118,17 @@ 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
 
 '\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

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