Clarify multiline a/i/c usage in Python API docs

Author: jph00

DEV.md

@@ -88,7 +88,7 @@ Maturin's `data` option in `pyproject.toml` points to `python/exhash.data/`. Fil
 
 The Rust core has three parsing functions:
 
-- `parse_commands_from_strs(&[&str])` — for the Python API; each string is one command, text blocks are the remaining lines (no `.` terminator; a trailing `.` line is literal text and the Python binding warns about this common mistake)
+- `parse_commands_from_strs(&[&str])` — for the Python API; each string is one command, and multiline `a/i/c` text blocks must be in that same string using newlines, e.g. `["12|abcd|c\nnew line 1\nnew line 2"]`. Do not use `.` terminators or split the inserted text into separate command entries; a trailing `.` line is literal text and the Python binding warns about this common mistake.
 - `parse_commands_from_script(&str)` — for script strings; commands separated by newlines, text blocks terminated by `.`
 - `parse_commands_from_args(&[String], &mut BufRead)` — for the CLI; each arg is a command, text blocks read from stdin terminated by `.`
 

README.md

@@ -118,7 +118,7 @@ view = lnhashview_file("f.py", start=1, end=260) # end past EOF is clamped
 
 ### Editing
 
-`exhash(text, cmds, sw=4)` takes the text and a required iterable of command strings (use `[]` for no-op). `sw` controls how far `<` and `>` shift. For `a`/`i`/`c` commands, lines after the command are the text block. Do not include an ex-style trailing `.` line here: unlike CLI/script mode, `exhash(text, cmds)` does not use one, and a final `.` line is inserted literally.
+`exhash(text, cmds, sw=4)` takes the text and a required iterable of command strings (use `[]` for no-op). `sw` controls how far `<` and `>` shift. For multiline `a`/`i`/`c` commands, include the inserted text in the same command string using newline characters, e.g. `["12|abcd|c\nnew line 1\nnew line 2"]`. Do not use `.` terminators, and do not split the text block into separate `cmds` entries. If you include a final `.` line, it is inserted literally and exhash emits a warning.
 
 ```py
 addr = lnhash(1, "foo")  # "1|a1b2|"
@@ -133,12 +133,15 @@ res = exhash(text, [f"{a1}s/foo/FOO/", f"{a2}s/bar/BAR/"])
 # Hashes are checked just-in-time per command.
 # If earlier commands change/shift a later target line, recompute lnhash first.
 
-# Append multiline text (no dot terminator)
+# Append multiline text in the same command string (no dot terminator)
 res = exhash(text, [f"{addr}a\nnew line 1\nnew line 2"])
 
 # Wrong for the Python API: the trailing "." would be inserted literally
 # res = exhash(text, [f"{addr}a\nnew line 1\nnew line 2\n."])
 
+# Also wrong: do not split the inserted text into separate cmds entries
+# res = exhash(text, [f"{addr}a", "new line 1", "new line 2"])
+
 # Change shift width for < and >
 res = exhash(text, [f"{addr}>1"], sw=2)
 

python/exhash/__init__.py

@@ -60,10 +60,11 @@ def exhash(text:str, cmds:list[str], sw:int=4):
 
     `sw` controls shift width for `<` and `>` and defaults to 4.
 
-    For a/i/c, remaining lines in the command string are the text block.
-    Do not include an ex-style trailing ``.`` terminator here: unlike CLI/script
-    mode, ``exhash(text, cmds)`` does not use one. If you include a final ``.``
-    line, it is inserted literally and exhash emits a warning.
+    For multiline a/i/c commands, include the inserted text in the same command
+    string using newline characters, e.g. ``["12|abcd|c\nnew line 1\nnew line 2"]``.
+    Do not use ``.`` terminators, and do not split the text block into separate
+    ``cmds`` entries. If you include a final ``.`` line, it is inserted literally
+    and exhash emits a warning.
 
     Returns an EditResult with attributes (also accessible as dict keys):
       lines     list of output lines
@@ -74,9 +75,6 @@ def exhash(text:str, cmds:list[str], sw:int=4):
 
     Call ``res.format_diff(context=1)`` for a unified-diff-style summary.
 
-    `cmds` is a required iterable of command strings. For `a`/`i`/`c`, include
-    the text block in the same command string after a newline.
-
     Examples::
 
       from exhash import exhash, lnhash, lnhashview
@@ -90,7 +88,7 @@ def exhash(text:str, cmds:list[str], sw:int=4):
 
 
 def exhash_file(path:str, cmds:list[str], sw:int=4, inplace:bool=False):
-    'Like ``exhash`` but reads from file at ``path``. Uses the same no-``.``-terminator rule for a/i/c text blocks. If the file is missing and the commands are valid on empty input (for example ``0|0000|a``), it is treated as empty and created on inplace write. If ``inplace``, writes back and returns diff string.'
+    'Like ``exhash`` but reads from file at ``path``. For multiline a/i/c commands, include the inserted text in the same command string using newline characters, e.g. ``["12|abcd|c\\nnew line 1\\nnew line 2"]``. Do not use ``.`` terminators, and do not split the text block into separate ``cmds`` entries. If the file is missing and the commands are valid on empty input (for example ``0|0000|a``), it is treated as empty and created on inplace write. If ``inplace``, writes back and returns diff string.'
     p = Path(path)
     try: text = p.read_text()
     except FileNotFoundError as e:

src/parse.rs

@@ -81,9 +81,11 @@ pub fn parse_commands_from_args(
 
 /// Parse commands from a list of individual command strings (for programmatic APIs).
 ///
-/// Each string is one command. For `a`/`i`/`c`, lines after the first are the text
-/// block (no `.` terminator needed; a trailing `.` line is literal text). For
-/// other commands, extra lines are an error.
+/// Each string is one command. For multiline `a`/`i`/`c`, include the text block
+/// in the same string using newline characters, e.g.
+/// `["12|abcd|c\nnew line 1\nnew line 2"]`. Do not use `.` terminators or split
+/// the text block into separate entries; a trailing `.` line is literal text.
+/// For other commands, extra lines are an error.
 pub fn parse_commands_from_strs(cmds: &[&str]) -> Result<Vec<Command>, EditError> {
     let mut out = Vec::with_capacity(cmds.len());
     for s in cmds {