fixes #11

Author: jph00

DEV.md

@@ -86,7 +86,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)
+- `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_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

@@ -108,7 +108,7 @@ view = lnhashview_file("f.py") # same but reads from file
 
 ### 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 (no `.` terminator needed):
+`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.
 
 ```py
 addr = lnhash(1, "foo")  # "1|a1b2|"
@@ -126,6 +126,9 @@ res = exhash(text, [f"{a1}s/foo/FOO/", f"{a2}s/bar/BAR/"])
 # Append multiline text (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."])
+
 # Change shift width for < and >
 res = exhash(text, [f"{addr}>1"], sw=2)
 

python/exhash/__init__.py

@@ -60,8 +60,10 @@ 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
-    (no '.' terminator needed, unlike the CLI).
+    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.
 
     Returns an EditResult with attributes (also accessible as dict keys):
       lines     list of output lines
@@ -88,7 +90,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``. If ``inplace``, writes back and returns diff string.'
+    'Like ``exhash`` but reads from file at ``path``. Uses the same no-``.``-terminator rule for a/i/c text blocks. If ``inplace``, writes back and returns diff string.'
     text = Path(path).read_text()
     r = _exhash(text, *cmds, sw=sw)
     if inplace:

src/parse.rs

@@ -71,7 +71,8 @@ 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). For other commands, extra lines are an error.
+/// block (no `.` terminator needed; 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 {

src/python.rs

@@ -1,6 +1,8 @@
-use pyo3::exceptions::PyValueError;
+use pyo3::exceptions::{PyUserWarning, PyValueError};
 use pyo3::prelude::*;
 
+use crate::{Command, Subcommand};
+
 #[pyclass]
 #[derive(Clone)]
 struct EditResultPy {
@@ -70,10 +72,11 @@ fn lnhashview(text: &str, start: Option<usize>, end: Option<usize>) -> PyResult<
 
 #[pyfunction]
 #[pyo3(name = "exhash", signature = (text, *cmds, sw=4))]
-fn py_exhash(text: &str, cmds: Vec<String>, sw: usize) -> PyResult<EditResultPy> {
+fn py_exhash(py: Python<'_>, text: &str, cmds: Vec<String>, sw: usize) -> PyResult<EditResultPy> {
     let cmd_refs: Vec<&str> = cmds.iter().map(|s| s.as_str()).collect();
     let parsed = crate::parse_commands_from_strs(&cmd_refs)
         .map_err(|e| PyValueError::new_err(e.to_string()))?;
+    warn_on_ex_style_dot_terminators(py, &cmds, &parsed)?;
     let res = crate::edit_text_with_sw(text, &parsed, sw)
         .map_err(|e| PyValueError::new_err(e.to_string()))?;
     Ok(EditResultPy {
@@ -92,3 +95,41 @@ fn exhash(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(py_exhash, m)?)?;
     Ok(())
 }
+
+fn warn_on_ex_style_dot_terminators(py: Python<'_>, inputs: &[String], parsed: &[Command]) -> PyResult<()> {
+    for (i, (input, cmd)) in inputs.iter().zip(parsed.iter()).enumerate() {
+        if command_has_text_block(cmd) && looks_like_ex_style_dot_terminator(input) {
+            let msg = format!(
+                "cmds[{i}] ends with a '.' line. In exhash(text, cmds), a/i/c text blocks do not use ex-style '.' terminators; that final '.' line will be inserted literally."
+            );
+            let warnings = py.import("warnings")?;
+            warnings.call_method1("warn", (msg, py.get_type::<PyUserWarning>(), 2))?;
+        }
+    }
+    Ok(())
+}
+
+fn command_has_text_block(cmd: &Command) -> bool {
+    match &cmd.cmd {
+        Subcommand::Append(_) | Subcommand::Insert(_) | Subcommand::Change(_) => true,
+        Subcommand::Global { cmd, .. } => matches!(
+            cmd.as_ref(),
+            Subcommand::Append(_) | Subcommand::Insert(_) | Subcommand::Change(_)
+        ),
+        _ => false,
+    }
+}
+
+fn looks_like_ex_style_dot_terminator(input: &str) -> bool {
+    let Some((_, rest)) = input.split_once('\n') else {
+        return false;
+    };
+    let mut lines: Vec<&str> = rest
+        .split('\n')
+        .map(|line| line.strip_suffix('\r').unwrap_or(line))
+        .collect();
+    while matches!(lines.last(), Some(&"")) {
+        lines.pop();
+    }
+    matches!(lines.last(), Some(&"."))
+}

tests/test_exhash.py

@@ -1,4 +1,4 @@
-import pytest
+import warnings, pytest
 from exhash import line_hash, lnhash, lnhashview, exhash
 
 def test_line_hash_returns_4_hex():
@@ -119,6 +119,21 @@ def test_exhash_append():
     assert res["lines"] == ["a", "x", "y", "b"]
     assert res["modified"] == [2, 3]
 
+def test_exhash_warns_on_ex_style_dot_terminator_for_text_block():
+    text = "a\nb\n"
+    addr = lnhash(1, "a")
+    with pytest.warns(UserWarning, match=r"final '\.' line will be inserted literally"): res = exhash(text, [addr+"a\nx\n."])
+    assert res["lines"] == ["a", "x", ".", "b"]
+
+def test_exhash_does_not_warn_for_nontrailing_dot_line():
+    text = "a\nb\n"
+    addr = lnhash(1, "a")
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        res = exhash(text, [addr+"a\n.\nx"])
+    assert res["lines"] == ["a", ".", "x", "b"]
+    assert not caught
+
 def test_exhash_insert():
     text = "a\nb\n"
     addr = lnhash(2, "b")
@@ -211,7 +226,7 @@ def test_exhash_literal_newline_in_replacement():
     assert res["lines"] == ["foo", "bar", "baz"]
 
 def test_exhash_file_read(tmp_path):
-    from exhash import lnhashview_file, exhash_file
+    from exhash import lnhashview_file
     f = tmp_path / "test.txt"
     f.write_text("hello\nworld\n")
     lines = lnhashview_file(str(f))
@@ -229,7 +244,7 @@ def test_exhash_file_inplace(tmp_path):
     assert f.read_text() == "baz\nbar\n"
 
 def test_exhash_file_inplace_no_change_on_error(tmp_path):
-    from exhash import exhash_file, lnhash
+    from exhash import exhash_file
     f = tmp_path / "test.txt"
     f.write_text("foo\nbar\n")
     with pytest.raises(ValueError): exhash_file(str(f), ["99|ffff|s/x/y/"], inplace=True)