exhash 0.3.2__tar.gz → 0.3.3__tar.gz

{exhash-0.3.2 → exhash-0.3.3}/Cargo.lock

@@ -25,7 +25,7 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "exhash"
-version = "0.3.2"
+version = "0.3.3"
 dependencies = [
  "pyo3",
  "regex",
@@ -48,9 +48,9 @@ dependencies = [
 
 [[package]]
 name = "libc"
-version = "0.2.185"
+version = "0.2.186"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
 
 [[package]]
 name = "memchr"

{exhash-0.3.2 → exhash-0.3.3}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "exhash"
-version = "0.3.2"
+version = "0.3.3"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 description = "Verified line-addressed file editor using lnhash addresses"

{exhash-0.3.2 → exhash-0.3.3}/DEV.md

@@ -18,7 +18,8 @@ src/
   bin/exhash.rs   CLI editor (atomic in-place edit, dry-run, stdin mode)
   bin/lnhashview.rs  CLI viewer
 python/exhash/
-  __init__.py     Python wrapper functions with typed/docstring API (+ exhash_result helper)
+  __init__.py     Python wrapper functions plus file-aware exhash_file orchestration
+  skill.py        pyskills entry point exposing exhash APIs for LLM tools
 python/exhash.data/scripts/
   exhash          native binary (built, not checked in)
   lnhashview      native binary (built, not checked in)
@@ -50,6 +51,9 @@ cargo test && pytest -q
 `edit_text` verifies lnhashes command-by-command against the current in-memory buffer, immediately before each command executes (not all upfront). If an earlier command shifts or rewrites a later target line, that later command will fail with a stale-hash error unless you recompute addresses.
 The `$` (last line) and `%` (whole file) address forms are resolved against the current buffer and do not require hashes.
 `edit_text_with_sw` exposes configurable shift width for `<` and `>`; `edit_text` defaults to `sw=4`.
+In CLI and Python file-helper flows, a missing file is treated as empty input only when the parsed command set is valid against an empty buffer (for example `0|0000|a`); otherwise the original file-not-found error is preserved.
+Python `exhash_file` adds the file-qualified orchestration layer. It parses optional `path:` prefixes, applies each command to the current in-memory buffer for that file, rejects cross-file source ranges, and writes changed files only after every command succeeds.
+`lnhashview` range requests clamp `end` past EOF to the last available line, while invalid `start` values still error.
 
 ## Release
 
@@ -86,9 +90,11 @@ 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 `.`
 
+File-qualified addresses are parsed by the Python `exhash_file` wrapper; the Rust parser and CLI remain single-buffer.
+
 Substitute parsing keeps Rust regex escapes intact (`\d`, `\w`, etc.) while still allowing escaped command delimiters (`\/`) in pattern and replacement.
 Transliteration uses `y/src/dst/` and validates equal character counts at parse time.

{exhash-0.3.2 → exhash-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: exhash
-Version: 0.3.2
+Version: 0.3.3
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Summary: Verified line-addressed file editor using lnhash addresses
@@ -52,6 +52,8 @@ lnhashview path/to/file.txt
 lnhashview path/to/file.txt 10 20
 ```
 
+If `end` is past EOF, `lnhashview` returns through the last available line instead of failing.
+
 ### Edit
 
 ```bash
@@ -80,6 +82,12 @@ exhash file.txt '%j'
 
 # Move a line to EOF using $ as the destination
 exhash file.txt '12|abcd|m$'
+
+# Create a missing file by treating it as empty input
+exhash new.txt '0|0000|a' <<'EOF'
+first line
+.
+EOF
 ```
 
 Substitute uses Rust regex syntax:
@@ -99,6 +107,8 @@ For `a/i/c` commands, provide the text block on stdin:
 printf "new line 1\nnew line 2\n.\n" | exhash file.txt "2|beef|a"
 ```
 
+If the file does not exist and the command set is valid on empty input, exhash treats it as an empty file and writes the result. For example, `0|0000|a` can create a new file.
+
 ### Stdin filter mode
 
 ```bash
@@ -117,13 +127,13 @@ from exhash import exhash, exhash_file, lnhash, lnhashview, lnhashview_file, lin
 
 ```py
 text = "foo\nbar\n"
-view = lnhashview(text)       # ["1|a1b2|  foo", "2|c3d4|  bar"]
-view = lnhashview_file("f.py") # same but reads from file
+view = lnhashview(text)                        # ["1|a1b2|  foo", "2|c3d4|  bar"]
+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|"
@@ -138,12 +148,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)
 
@@ -157,18 +170,46 @@ res = exhash("foo\nbar\n", [f"{a1},{a2}s/foo\nbar/replaced/"])
 
 ### File helpers
 
-`exhash_file` and `lnhashview_file` read directly from a file path:
+`lnhashview_file` reads directly from one file path. `exhash_file(path, cmds, sw=4, inplace=False)` uses `path` as the default file context for unqualified addresses, and also accepts file-qualified source and `m`/`t` destination addresses:
 
 ```py
 view = lnhashview_file("file.py")
 
-# Returns EditResult, file unchanged
+# Returns FileSetEditResult, files unchanged
 res = exhash_file("file.py", [f"{addr}s/foo/bar/"])
+print(res.changed)          # ["file.py"]
+print(res["file.py"].lines)
+print(res.format_diff())    # includes --- file.py / +++ file.py headers
 
-# With inplace=True, writes back on success and returns diff string
+# With inplace=True, writes changed files after every command succeeds
+# and returns the combined diff string.
 diff = exhash_file("file.py", [f"{addr}s/foo/bar/"], inplace=True)
+
+# Missing files are treated as empty only when the command is valid on empty input.
+diff = exhash_file("new.py", ["0|0000|a\nprint('hi')"], inplace=True)
+
+# File-qualified addresses can edit or transfer lines across files.
+cmds = [
+    "src/a.py:24|8f12|,38|c0de|m src/b.py:$",
+    r"src/a.py:5|91aa|s/from \.b import old/from \.b import helper/",
+]
+diff = exhash_file("src/a.py", cmds, inplace=True)
 ```
 
+A file prefix is separated from the address with `:`. Escape literal colons in filenames as `\:` and literal backslashes as `\\`.
+
+`exhash_file(..., inplace=False)` returns a `FileSetEditResult`:
+
+- `res.files` — dict of path to `FileEditResult`
+- `res.changed` — changed paths, in first-touch order
+- `res.default_path` — the default path passed to `exhash_file`
+- `res[path]` — shorthand for `res.files[path]`
+- `res.format_diff(context=1)` — combined diff with `--- path` / `+++ path` headers
+
+### Pyskill
+
+The package registers `exhash.skill` as a pyskill exposing the primary Python APIs with LLM-oriented workflow docs. Use `doc(exhash.skill)` after importing it through a pyskills host.
+
 ### EditResult
 
 `exhash()` returns an `EditResult` with attributes (also accessible via `res["key"]`):
@@ -184,6 +225,8 @@ diff = exhash_file("file.py", [f"{addr}s/foo/bar/"], inplace=True)
 ```py
 res = exhash(text, [f"{addr}s/foo/baz/"])
 print(res.format_diff())
+# --- original
+# +++ modified
 # -1|a1b2|  foo
 # +1|c3d4|  baz
 #  2|e5f6|  bar

{exhash-0.3.2 → exhash-0.3.3}/README.md

@@ -37,6 +37,8 @@ lnhashview path/to/file.txt
 lnhashview path/to/file.txt 10 20
 ```
 
+If `end` is past EOF, `lnhashview` returns through the last available line instead of failing.
+
 ### Edit
 
 ```bash
@@ -65,6 +67,12 @@ exhash file.txt '%j'
 
 # Move a line to EOF using $ as the destination
 exhash file.txt '12|abcd|m$'
+
+# Create a missing file by treating it as empty input
+exhash new.txt '0|0000|a' <<'EOF'
+first line
+.
+EOF
 ```
 
 Substitute uses Rust regex syntax:
@@ -84,6 +92,8 @@ For `a/i/c` commands, provide the text block on stdin:
 printf "new line 1\nnew line 2\n.\n" | exhash file.txt "2|beef|a"
 ```
 
+If the file does not exist and the command set is valid on empty input, exhash treats it as an empty file and writes the result. For example, `0|0000|a` can create a new file.
+
 ### Stdin filter mode
 
 ```bash
@@ -102,13 +112,13 @@ from exhash import exhash, exhash_file, lnhash, lnhashview, lnhashview_file, lin
 
 ```py
 text = "foo\nbar\n"
-view = lnhashview(text)       # ["1|a1b2|  foo", "2|c3d4|  bar"]
-view = lnhashview_file("f.py") # same but reads from file
+view = lnhashview(text)                        # ["1|a1b2|  foo", "2|c3d4|  bar"]
+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|"
@@ -123,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)
 
@@ -142,18 +155,46 @@ res = exhash("foo\nbar\n", [f"{a1},{a2}s/foo\nbar/replaced/"])
 
 ### File helpers
 
-`exhash_file` and `lnhashview_file` read directly from a file path:
+`lnhashview_file` reads directly from one file path. `exhash_file(path, cmds, sw=4, inplace=False)` uses `path` as the default file context for unqualified addresses, and also accepts file-qualified source and `m`/`t` destination addresses:
 
 ```py
 view = lnhashview_file("file.py")
 
-# Returns EditResult, file unchanged
+# Returns FileSetEditResult, files unchanged
 res = exhash_file("file.py", [f"{addr}s/foo/bar/"])
+print(res.changed)          # ["file.py"]
+print(res["file.py"].lines)
+print(res.format_diff())    # includes --- file.py / +++ file.py headers
 
-# With inplace=True, writes back on success and returns diff string
+# With inplace=True, writes changed files after every command succeeds
+# and returns the combined diff string.
 diff = exhash_file("file.py", [f"{addr}s/foo/bar/"], inplace=True)
+
+# Missing files are treated as empty only when the command is valid on empty input.
+diff = exhash_file("new.py", ["0|0000|a\nprint('hi')"], inplace=True)
+
+# File-qualified addresses can edit or transfer lines across files.
+cmds = [
+    "src/a.py:24|8f12|,38|c0de|m src/b.py:$",
+    r"src/a.py:5|91aa|s/from \.b import old/from \.b import helper/",
+]
+diff = exhash_file("src/a.py", cmds, inplace=True)
 ```
 
+A file prefix is separated from the address with `:`. Escape literal colons in filenames as `\:` and literal backslashes as `\\`.
+
+`exhash_file(..., inplace=False)` returns a `FileSetEditResult`:
+
+- `res.files` — dict of path to `FileEditResult`
+- `res.changed` — changed paths, in first-touch order
+- `res.default_path` — the default path passed to `exhash_file`
+- `res[path]` — shorthand for `res.files[path]`
+- `res.format_diff(context=1)` — combined diff with `--- path` / `+++ path` headers
+
+### Pyskill
+
+The package registers `exhash.skill` as a pyskill exposing the primary Python APIs with LLM-oriented workflow docs. Use `doc(exhash.skill)` after importing it through a pyskills host.
+
 ### EditResult
 
 `exhash()` returns an `EditResult` with attributes (also accessible via `res["key"]`):
@@ -169,6 +210,8 @@ diff = exhash_file("file.py", [f"{addr}s/foo/bar/"], inplace=True)
 ```py
 res = exhash(text, [f"{addr}s/foo/baz/"])
 print(res.format_diff())
+# --- original
+# +++ modified
 # -1|a1b2|  foo
 # +1|c3d4|  baz
 #  2|e5f6|  bar

{exhash-0.3.2 → exhash-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "exhash"
-version = "0.3.2"
+version = "0.3.3"
 description = "Verified line-addressed file editor using lnhash addresses"
 license = {text = "MIT OR Apache-2.0"}
 requires-python = ">=3.10"
@@ -19,6 +19,8 @@ classifiers = [
 Homepage = "https://github.com/AnswerDotAI/exhash"
 Repository = "https://github.com/AnswerDotAI/exhash"
 Issues = "https://github.com/AnswerDotAI/exhash/issues"
+[project.entry-points.pyskills]
+exhash = "exhash.skill"
 
 [tool.maturin]
 features = ["extension-module"]

exhash-0.3.3/python/exhash/__init__.py

@@ -0,0 +1,337 @@
+import re
+from difflib import SequenceMatcher
+from pathlib import Path
+from .exhash import line_hash as _line_hash, lnhash as _lnhash, lnhashview as _lnhashview, exhash as _exhash
+
+def line_hash(line:str) -> str:
+    'Return a 4-char lowercase hex hash for a single line of text.'
+    return _line_hash(line)
+
+
+def lnhash(lineno:int, line:str) -> str:
+    'Return an lnhash address ``lineno|hash|`` for ``line`` at 1-based ``lineno``.'
+    return _lnhash(lineno, line)
+
+
+def lnhashview(text:str, start:int=None, end:int=None) -> list[str]:
+    'Return lines formatted as ``lineno|hash|  content``. Optional 1-based ``start``/``end`` filter the range; ``end`` past EOF is clamped.'
+    return _lnhashview(text, start, end)
+
+
+def lnhashview_file(path:str, start:int=None, end:int=None) -> list[str]:
+    'Return lines formatted as ``lineno|hash|  content`` for file at ``path``. Optional 1-based ``start``/``end`` filter the range; ``end`` past EOF is clamped.'
+    return _lnhashview(Path(path).read_text(), start, end)
+
+
+def exhash(text:str, cmds:list[str], sw:int=4):
+    """Verified line-addressed editor. Apply commands to `text`, return an EditResult.
+
+    Commands primarily use lnhash addresses: ``lineno|hash|cmd`` where hash is
+    a 4-char hex content hash. Use ``lnhashview(text)`` or
+    ``lnhash(lineno, line)`` to get hashed addresses.
+    Each command's hashes are verified against current text immediately before
+    that command executes.
+
+    Addressing:
+      Single:   ``12|a3f2|cmd``
+      Range:    ``12|a3f2|,15|b1c3|cmd``
+      Last:     ``$cmd`` (last line)
+      Whole:    ``%cmd`` (whole file, same as ``1,$``)
+      Special:  ``0|0000|`` targets before line 1 (only with a or i)
+
+    Commands:
+      s/pat/rep/[flags]  Substitute using Rust regex syntax.
+                         Replacement supports $1, $0, ${name}. Flags: g=all, i=case-insensitive
+                         Any non-alphanumeric delimiter works: s@pat@rep@, s|pat|rep|g
+                         Literal newlines in pat/rep are supported (joins/splits lines)
+      y/src/dst/         Transliterate chars in-place (also supports custom delimiters;
+                         source and destination lengths must match)
+      d                  Delete line(s)
+      a                  Append text after line
+      i                  Insert text before line
+      c                  Change/replace line(s)
+      j                  Join with next line; with range, joins all
+      m dest             Move line(s) after dest address
+      t dest             Copy line(s) after dest address
+      >[n]               Indent n levels (default 1, `sw` spaces each)
+      <[n]               Dedent n levels (default 1, `sw` spaces each)
+      sort               Sort lines alphabetically
+      p                  Print (include in output without changing)
+      g/pat/cmd          Global: run cmd on matching lines (custom delimiters ok: g@pat@cmd)
+      g!/pat/cmd         Inverted global (also v/pat/cmd; custom delimiters ok)
+
+    `sw` controls shift width for `<` and `>` and defaults to 4.
+
+    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
+      hashes    lnhash for each output line
+      modified  1-based line numbers of modified/added lines
+      deleted   1-based line numbers of removed lines (in original)
+      origins   for each output line, the 1-based original line number (None if inserted)
+
+    Call ``res.format_diff(context=1)`` for a unified-diff-style summary.
+    Non-empty diffs start with ``--- original`` and ``+++ modified`` headers.
+
+    Examples::
+
+      from exhash import exhash, lnhash, lnhashview
+      text = "foo\\nbar\\n"
+      addr = lnhash(1, "foo")           # "1|a1b2|"
+      res = exhash(text, [f"{addr}s/foo/baz/"])
+      print(res["lines"])                # ["baz", "bar"]
+      print(res.format_diff())           # unified-diff-style summary
+    """
+    return _exhash(text, *cmds, sw=sw)
+
+
+class FileEditResult:
+    'Edited state for one file.'
+    def __init__(self, path, original_lines, lines):
+        self.path = _norm_path(path)
+        self.original_lines = list(original_lines)
+        self.lines = list(lines)
+        self.hashes = [lnhash(i + 1, line) for i, line in enumerate(self.lines)]
+
+    @property
+    def changed(self): return self.original_lines != self.lines
+
+    def __getitem__(self, key):
+        if key in {"lines", "hashes", "original_lines"}: return getattr(self, key)
+        raise KeyError(key)
+
+    def format_diff(self, context=1): return _format_file_diff(self.path, self.original_lines, self.lines, context)
+
+
+class FileSetEditResult:
+    'Edited state for an exhash_file command set.'
+    def __init__(self, files, default_path):
+        self.files = files
+        self.default_path = default_path
+        self.changed = [path for path, result in files.items() if result.changed]
+
+    def __getitem__(self, path): return self.files[_norm_path(path)]
+
+    def format_diff(self, context=1): return ''.join(self.files[path].format_diff(context) for path in self.changed)
+
+
+_ADDR_RE = re.compile(r'(?:\$|%|\d+\|[0-9a-fA-F]{4}\|)')
+_LNHASH_RE = re.compile(r'(\d+)\|([0-9a-fA-F]{4})\|')
+
+
+def _norm_path(path): return str(Path(path))
+
+
+def _text_from_lines(lines): return '\n'.join(lines) + ('\n' if lines else '')
+
+
+def _write_lines(path, lines): Path(path).write_text(_text_from_lines(lines))
+
+
+def _format_file_diff(path, old_lines, new_lines, context=1):
+    if old_lines == new_lines: return ''
+    events = []
+    for tag, i1, i2, j1, j2 in SequenceMatcher(a=old_lines, b=new_lines, autojunk=False).get_opcodes():
+        if tag == 'equal': events += [(' ', j + 1, new_lines[j]) for j in range(j1, j2)]
+        elif tag == 'delete': events += [('-', i + 1, old_lines[i]) for i in range(i1, i2)]
+        elif tag == 'insert': events += [('+', j + 1, new_lines[j]) for j in range(j1, j2)]
+        elif tag == 'replace':
+            events += [('-', i + 1, old_lines[i]) for i in range(i1, i2)]
+            events += [('+', j + 1, new_lines[j]) for j in range(j1, j2)]
+    interesting = set()
+    for i, (tag, _, _) in enumerate(events):
+        if tag != ' ': interesting.update(range(max(0, i - context), min(len(events), i + context + 1)))
+    out, last = [f'--- {path}', f'+++ {path}'], None
+    for i in sorted(interesting):
+        if last is not None and i > last + 1: out.append('---')
+        tag, lineno, line = events[i]
+        out.append(f'{tag}{lnhash(lineno, line)}  {line}')
+        last = i
+    return '\n'.join(out) + '\n'
+
+
+def _unescape_path(path):
+    out, escaped = [], False
+    for ch in path:
+        if escaped:
+            if ch not in ':\\': out.append('\\')
+            out.append(ch)
+            escaped = False
+        elif ch == '\\': escaped = True
+        else: out.append(ch)
+    if escaped: out.append('\\')
+    return ''.join(out)
+
+
+def _split_file_prefix(s):
+    if _ADDR_RE.match(s): return None, s
+    escaped = False
+    for i, ch in enumerate(s):
+        if escaped:
+            escaped = False
+            continue
+        if ch == '\\':
+            escaped = True
+            continue
+        if ch == ':' and _ADDR_RE.match(s[i + 1:]):
+            path = _unescape_path(s[:i])
+            if not path: raise ValueError('empty filename prefix')
+            return _norm_path(path), s[i + 1:]
+    return None, s
+
+
+def _parse_fileaddr(s, default_path):
+    path, rest = _split_file_prefix(s)
+    path = path or default_path
+    m = _ADDR_RE.match(rest)
+    if not m: raise ValueError(f'expected exhash address near {s[:40]!r}')
+    return path, m.group(0), rest[m.end():]
+
+
+def _parse_file_command(raw, default_path):
+    if not raw.strip(): return None
+    src, addr1, rest = _parse_fileaddr(raw.lstrip(), default_path)
+    has_comma, addr2, local = False, None, addr1
+    if rest.startswith(','):
+        has_comma = True
+        src2, addr2, rest = _parse_fileaddr(rest[1:], src)
+        if src2 != src: raise ValueError('cross-file ranges are invalid')
+        local += ',' + addr2
+    local += rest
+    body = rest.lstrip()
+    op = body[:1] if body[:1] in {'m', 't'} else None
+    dest = dest_addr = None
+    if op:
+        dest, dest_addr, tail = _parse_fileaddr(body[1:].strip(), src)
+        if tail.strip(): raise ValueError(f'unexpected trailing characters after destination: {tail!r}')
+    return dict(src=src, addr1=addr1, addr2=addr2, has_comma=has_comma, rest=rest, local=local, op=op, dest=dest, dest_addr=dest_addr)
+
+
+def _load_buffer(buffers, path, missing_ok=False):
+    if path in buffers: return buffers[path]
+    p = Path(path)
+    try: lines = p.read_text().splitlines()
+    except FileNotFoundError:
+        if not missing_ok: raise
+        if not p.parent.exists(): raise
+        lines = []
+    buffers[path] = dict(path=path, original=list(lines), lines=list(lines))
+    return buffers[path]
+
+
+def _can_create_missing(parsed): return parsed['addr1'] == '0|0000|' and parsed['rest'].lstrip()[:1] in {'a', 'i'}
+
+
+def _split_lnhash_addr(addr):
+    m = _LNHASH_RE.fullmatch(addr)
+    if not m: raise ValueError(f'expected lnhash address, got {addr!r}')
+    return int(m.group(1)), m.group(2).lower()
+
+
+def _line_no(lines, addr, allow_zero=False):
+    if addr == '$':
+        if not lines: raise ValueError("address '$' out of range on empty file")
+        return len(lines)
+    if addr == '%': raise ValueError('% is only allowed as a source range')
+    lineno, expected = _split_lnhash_addr(addr)
+    if lineno == 0:
+        if expected != '0000': raise ValueError('0|0000| must have hash 0000')
+        if allow_zero: return 0
+        raise ValueError('address 0 is not allowed here')
+    if lineno > len(lines): raise ValueError(f'address out of range: {lineno} > {len(lines)}')
+    actual = line_hash(lines[lineno - 1])
+    if actual != expected: raise ValueError(f'stale lnhash at line {lineno}: expected {expected}, got {actual}')
+    return lineno
+
+
+def _source_indexes(lines, parsed):
+    if parsed['addr1'] == '%':
+        if parsed['has_comma'] or parsed['addr2'] is not None: raise ValueError('% is already a whole-file range')
+        return (0, len(lines) - 1) if lines else (0, -1)
+    start = _line_no(lines, parsed['addr1'])
+    end = _line_no(lines, parsed['addr2']) if parsed['addr2'] is not None else start
+    if start > end: raise ValueError(f'invalid range: {start}..{end}')
+    return start - 1, end - 1
+
+
+def _dest_index(lines, addr):
+    if addr == '%': raise ValueError('destination % is not allowed')
+    return _line_no(lines, addr, allow_zero=True)
+
+
+def _apply_transfer(buffers, parsed):
+    src = _load_buffer(buffers, parsed['src'])
+    dst = _load_buffer(buffers, parsed['dest'], missing_ok=parsed['dest_addr'] == '0|0000|')
+    s, e = _source_indexes(src['lines'], parsed)
+    dest = _dest_index(dst['lines'], parsed['dest_addr'])
+    segment = src['lines'][s:e + 1] if s <= e else []
+    if parsed['op'] == 't':
+        dst['lines'][dest:dest] = list(segment)
+        return
+    if src is dst:
+        if s <= e and s < dest <= e + 1: raise ValueError('destination is within moved range')
+        del src['lines'][s:e + 1]
+        insert_at = dest if dest <= s else dest - len(segment)
+        src['lines'][insert_at:insert_at] = segment
+    else:
+        del src['lines'][s:e + 1]
+        dst['lines'][dest:dest] = segment
+
+
+def _apply_file_command(buffers, parsed, sw):
+    if parsed['op']:
+        _apply_transfer(buffers, parsed)
+        return
+    buf = _load_buffer(buffers, parsed['src'], missing_ok=_can_create_missing(parsed))
+    res = exhash(_text_from_lines(buf['lines']), [parsed['local']], sw=sw)
+    buf['lines'] = list(res['lines'])
+
+
+def exhash_file(path:str, cmds:list[str], sw:int=4, inplace:bool=False):
+    r'''Read files, apply file-aware exhash commands, and return per-file results or a combined diff.
+
+    Core command syntax is the same as ``exhash(text, cmds, sw=sw)``; run
+    ``doc(exhash)`` for the full command reference. Use ``path`` as the default
+    file context for unqualified addresses. Prefix any source address, and any
+    ``m``/``t`` destination, with ``path:`` to target another file::
+
+      src/a.py:12|a3f2|s/foo/bar/
+      src/a.py:10|aaaa|,20|bbbb|m src/b.py:$
+      src/a.py:10|aaaa|t new.py:0|0000|
+
+    A range must stay within one file. The second address may omit the filename
+    and inherit it from the first address. Cross-file ranges are invalid. Escape
+    literal colons in filenames as ``\:`` and literal backslashes as ``\\\\``.
+
+    For multiline ``a``/``i``/``c`` commands, include the inserted text in the
+    same command string using newline characters. Do not use ``.`` terminators,
+    and do not split the text block into separate ``cmds`` entries.
+
+    Missing files are treated as empty only when the command is valid against an
+    empty buffer, such as ``0|0000|a``/``0|0000|i`` or an ``m``/``t`` destination
+    of ``0|0000|``.
+
+    With ``inplace=False``, return a ``FileSetEditResult`` with ``files``,
+    ``changed``, ``default_path``, ``res[path]``, and
+    ``res.format_diff(context=1)``. With ``inplace=True``, write changed files
+    only after every command succeeds and return the combined diff string. If
+    any command fails, write nothing.
+    '''
+    default_path, buffers = _norm_path(path), {}
+    for raw in cmds:
+        parsed = _parse_file_command(raw, default_path)
+        if parsed is not None: _apply_file_command(buffers, parsed, sw)
+    if not buffers: _load_buffer(buffers, default_path)
+    files = {path: FileEditResult(path, buf['original'], buf['lines']) for path, buf in buffers.items()}
+    result = FileSetEditResult(files, default_path)
+    if inplace:
+        for path in result.changed: _write_lines(path, result[path].lines)
+        return result.format_diff()
+    return result
+
+