@oh-my-pi/hashline 17.2.0 → 17.2.2

package/src/block.ts

@@ -139,7 +139,13 @@ export function resolveBlockEdits(
 							: pasteAfterBlockUnresolvedLoweredWarning(edit.anchor.line),
 					);
 					const cursor: Cursor = { kind: "after_anchor", anchor: { line: edit.anchor.line } };
-					resolved.push({ kind: "paste", cursor, lineNum: edit.lineNum, index: synthIndex++ });
+					resolved.push({
+						kind: "paste",
+						at: { kind: "gap", cursor },
+						...(edit.register === undefined ? {} : { register: edit.register }),
+						lineNum: edit.lineNum,
+						index: synthIndex++,
+					});
 					continue;
 				}
 				options.onWarning?.(
@@ -165,7 +171,9 @@ export function resolveBlockEdits(
 			const suggestions: BlockDiagnosticSuggestions = {};
 			if (nextBlock) suggestions.nextBlock = nextBlock;
 			if (enclosingBlock) suggestions.enclosingBlock = enclosingBlock;
-			throw new Error(`line ${edit.lineNum}: ${blockUnresolvedMessage(edit.anchor.line, op, lines, suggestions)}`);
+			throw new Error(
+				`line ${edit.lineNum}: ${blockUnresolvedMessage(edit.anchor.line, op, lines, suggestions, edit.register)}`,
+			);
 		}
 		if (span.start === span.end) {
 			// A single-line block resolution means line N is a bare statement, not
@@ -193,7 +201,8 @@ export function resolveBlockEdits(
 			// claiming a depth inside the block back across its trailing closers.
 			resolved.push({
 				kind: "paste",
-				cursor: { kind: "after_anchor", anchor: { line: span.end } },
+				at: { kind: "gap", cursor: { kind: "after_anchor", anchor: { line: span.end } } },
+				...(edit.register === undefined ? {} : { register: edit.register }),
 				lineNum: edit.lineNum,
 				index: synthIndex++,
 				blockStart: span.start,
@@ -205,6 +214,7 @@ export function resolveBlockEdits(
 			resolved.push({
 				kind: "cut",
 				range: { start: { line: span.start }, end: { line: span.end } },
+				...(edit.register === undefined ? {} : { register: edit.register }),
 				lineNum: edit.lineNum,
 				index: synthIndex++,
 			});
@@ -232,8 +242,20 @@ export function resolveBlockEdits(
 			}
 			continue;
 		}
-		// Mirror `SWAP start.=end:`: replacement inserts at `span.start`, then
-		// one delete per line across the resolved span.
+		if (edit.register !== undefined) {
+			// Register-backed block replace (`PUT N* @reg`): expand to a span paste
+			// over the resolved block range.
+			resolved.push({
+				kind: "paste",
+				at: { kind: "span", range: { start: { line: span.start }, end: { line: span.end } } },
+				register: edit.register,
+				lineNum: edit.lineNum,
+				index: synthIndex++,
+			});
+			continue;
+		}
+		// Body-backed block replace (`PUT N*:` + body): replacement inserts at
+		// `span.start`, then one delete per line across the resolved span.
 		for (const payload of edit.payloads) {
 			const cursor: Cursor = { kind: "before_anchor", anchor: { line: span.start } };
 			resolved.push({

package/src/clipboard.ts

@@ -1,13 +1,14 @@
 /**
- * Clipboard register support for `CUT` / `PASTE` ops.
+ * Clipboard register support for `CUT` and register `PUT` ops.
  *
- * `CUT` captures its current source lines before ordinary delete edits apply.
- * `PASTE` expands the latest capture into inserts. One register flows through
- * patch sections in authored order, so content moves across files; the latest
- * cut wins and paste does not consume it.
+ * `CUT` captures source lines before ordinary delete edits apply. Register
+ * `PUT`s expand captured lines into inserts (plus per-line deletes when the
+ * target is a `span`). Named registers (`named: Map`) persist across edit
+ * batches when host-owned (`PatcherOptions.clipboard`); the anonymous register
+ * (`lines`) is batch-local and resets between calls.
  */
-import { HL_CUT_KEYWORD, HL_RANGE_SEP } from "./format";
-import { EMPTY_PASTE } from "./messages";
+import { HL_CUT_KEYWORD, HL_PUT_KEYWORD, HL_RANGE_SEP } from "./format";
+import { ambiguousAnonymousPasteMessage, EMPTY_PASTE, unknownRegisterMessage } from "./messages";
 import { cloneCursor } from "./tokenizer";
 import type { Clipboard, Edit } from "./types";
 
@@ -15,29 +16,84 @@ type CutEdit = Extract<Edit, { kind: "cut" }>;
 
 function describeCutEdit(edit: CutEdit): string {
 	const { start, end } = edit.range;
-	const range = start.line === end.line ? `${start.line}` : `${start.line}${HL_RANGE_SEP}${end.line}`;
-	return `${HL_CUT_KEYWORD} ${range}`;
+	const span = start.line === end.line ? `${start.line}` : `${start.line}${HL_RANGE_SEP}${end.line}`;
+	const reg = edit.register ? ` @${edit.register}` : "";
+	return `${HL_CUT_KEYWORD} ${span}${reg}`;
 }
 
-/** True when at least one edit reads or writes the clipboard register. */
+/** True when at least one edit reads or writes a clipboard register. */
 export function hasClipboardEdit(edits: readonly Edit[]): boolean {
 	return edits.some(
 		edit =>
 			edit.kind === "cut" ||
 			edit.kind === "paste" ||
-			(edit.kind === "block" && (edit.mode === "cut" || edit.mode === "paste_after")),
+			(edit.kind === "block" && (edit.mode === "cut" || edit.mode === "paste_after" || edit.register !== undefined)),
 	);
 }
 
 /** Optional knobs for {@link resolveClipboardEdits}. */
 export interface ResolveClipboardEditsOptions {
-	/** `PASTE` with an empty register: `throw` (default) or `drop` (streaming previews). */
+	/** `PUT` with an empty register: `throw` (default) or `drop` (streaming previews). */
 	onEmptyPaste?: "throw" | "drop";
 }
 
+/**
+ * Read lines from a register. Throws on missing/ambiguous register unless `onEmptyPaste === "drop"`.
+ */
+function readRegister(
+	register: string | undefined,
+	clipboard: Clipboard,
+	lineNum: number,
+	onEmptyPaste: "throw" | "drop",
+): readonly string[] | null {
+	if (register !== undefined) {
+		const lines = clipboard.named?.get(register);
+		if (lines !== undefined) return lines;
+		if (onEmptyPaste === "drop") return null;
+		const known = clipboard.named ? [...clipboard.named.keys()] : [];
+		throw new Error(`line ${lineNum}: ${unknownRegisterMessage(register, known)}`);
+	}
+
+	const pending = clipboard.pendingAnonCuts ?? [];
+	if (pending.length > 1) {
+		if (onEmptyPaste === "drop") return null;
+		throw new Error(`line ${lineNum}: ${ambiguousAnonymousPasteMessage(pending)}`);
+	}
+
+	const lines = clipboard.lines;
+	if (lines === undefined) {
+		if (onEmptyPaste === "drop") return null;
+		throw new Error(`line ${lineNum}: ${EMPTY_PASTE}`);
+	}
+	// Successful anonymous read clears the pending ambiguity counter for follow-up pastes.
+	clipboard.pendingAnonCuts = [];
+	return lines;
+}
+
+/**
+ * Write lines into a register (named or anonymous).
+ */
+function writeRegister(edit: CutEdit, fileLines: readonly string[], clipboard: Clipboard): void {
+	const { start, end } = edit.range;
+	if (start.line < 1 || end.line > fileLines.length) {
+		throw new Error(
+			`line ${edit.lineNum}: \`${describeCutEdit(edit)}\` is out of range (file has ${fileLines.length} lines).`,
+		);
+	}
+	const captured = fileLines.slice(start.line - 1, end.line);
+	if (edit.register !== undefined) {
+		clipboard.named ??= new Map();
+		clipboard.named.set(edit.register, captured);
+	} else {
+		clipboard.lines = captured;
+		clipboard.pendingAnonCuts ??= [];
+		clipboard.pendingAnonCuts.push(describeCutEdit(edit));
+	}
+}
+
 /**
  * Resolve clipboard edits against the original file lines in authored order.
- * Cuts fill the register and emit nothing; pastes become plain inserts.
+ * Cuts fill the register and emit nothing; pastes expand to inserts (+ deletes for span targets).
  */
 export function resolveClipboardEdits(
 	edits: readonly Edit[],
@@ -49,32 +105,55 @@ export function resolveClipboardEdits(
 	const onEmptyPaste = options.onEmptyPaste ?? "throw";
 	const resolved: Edit[] = [];
 	let synthIndex = 0;
+
 	for (const edit of edits) {
 		if (edit.kind === "cut") {
-			const { start, end } = edit.range;
-			if (start.line < 1 || end.line > fileLines.length) {
-				throw new Error(
-					`line ${edit.lineNum}: \`${describeCutEdit(edit)}\` is out of range (file has ${fileLines.length} lines).`,
-				);
-			}
-			clipboard.lines = fileLines.slice(start.line - 1, end.line);
+			writeRegister(edit, fileLines, clipboard);
 			continue;
 		}
 		if (edit.kind === "paste") {
-			const lines = clipboard.lines;
-			if (lines === undefined) {
-				if (onEmptyPaste === "drop") continue;
-				throw new Error(`line ${edit.lineNum}: ${EMPTY_PASTE}`);
-			}
-			for (const text of lines) {
-				resolved.push({
-					kind: "insert",
-					cursor: cloneCursor(edit.cursor),
-					text,
-					lineNum: edit.lineNum,
-					index: synthIndex++,
-					...(edit.blockStart === undefined ? {} : { blockStart: edit.blockStart }),
-				});
+			const lines = readRegister(edit.register, clipboard, edit.lineNum, onEmptyPaste);
+			if (lines === null) continue;
+
+			if (edit.at.kind === "gap") {
+				for (const text of lines) {
+					resolved.push({
+						kind: "insert",
+						cursor: cloneCursor(edit.at.cursor),
+						text,
+						lineNum: edit.lineNum,
+						index: synthIndex++,
+						...(edit.blockStart === undefined ? {} : { blockStart: edit.blockStart }),
+					});
+				}
+			} else {
+				// Span paste: insert replacement lines before start, then delete span lines.
+				const range = edit.at.range;
+				if (range.start.line < 1 || range.end.line > fileLines.length) {
+					const reg = edit.register ? ` @${edit.register}` : "";
+					throw new Error(
+						`line ${edit.lineNum}: \`${HL_PUT_KEYWORD} ${range.start.line}${HL_RANGE_SEP}${range.end.line}${reg}\` is out of range (file has ${fileLines.length} lines).`,
+					);
+				}
+				const cursor = { kind: "before_anchor" as const, anchor: { line: range.start.line } };
+				for (const text of lines) {
+					resolved.push({
+						kind: "insert",
+						cursor: cloneCursor(cursor),
+						text,
+						lineNum: edit.lineNum,
+						index: synthIndex++,
+						mode: "replacement",
+					});
+				}
+				for (let line = range.start.line; line <= range.end.line; line++) {
+					resolved.push({
+						kind: "delete",
+						anchor: { line },
+						lineNum: edit.lineNum,
+						index: synthIndex++,
+					});
+				}
 			}
 			continue;
 		}
@@ -83,15 +162,28 @@ export function resolveClipboardEdits(
 	return resolved;
 }
 
+/** Start a batch with persisted named registers but no anonymous state. */
+export function startClipboardBatch(source?: Clipboard): Clipboard {
+	if (source?.named === undefined) return {};
+	return { named: new Map(source.named) };
+}
+
 /** Create a transactional working copy of a clipboard register. */
 export function forkClipboard(source?: Clipboard): Clipboard {
-	return source === undefined ? {} : { ...source };
+	if (source === undefined) return {};
+	return {
+		...(source.lines === undefined ? {} : { lines: [...source.lines] }),
+		...(source.named === undefined ? {} : { named: new Map(source.named) }),
+		...(source.pendingAnonCuts === undefined ? {} : { pendingAnonCuts: [...source.pendingAnonCuts] }),
+	};
 }
 
-/** Publish a clipboard fork back to its source register. */
+/** Publish a clipboard fork back to its source register (only named registers persist across batches). */
 export function commitClipboard(fork: Clipboard, target: Clipboard): void {
-	if (fork.lines === undefined) delete target.lines;
-	else target.lines = fork.lines;
+	if (fork.named !== undefined) {
+		target.named ??= new Map();
+		for (const [k, v] of fork.named) target.named.set(k, v);
+	}
 }
 
 /**
@@ -99,12 +191,19 @@ export function commitClipboard(fork: Clipboard, target: Clipboard): void {
  * mutating the register or reading file content.
  */
 export function validateClipboardSequence(edits: readonly Edit[], clipboard: Clipboard): void {
-	let hasLines = clipboard.lines !== undefined;
+	const fork = forkClipboard(clipboard);
 	for (const edit of edits) {
 		if (edit.kind === "cut") {
-			hasLines = true;
-		} else if (edit.kind === "paste" && !hasLines) {
-			throw new Error(`line ${edit.lineNum}: ${EMPTY_PASTE}`);
+			if (edit.register !== undefined) {
+				fork.named ??= new Map();
+				fork.named.set(edit.register, []);
+			} else {
+				fork.lines = [];
+				fork.pendingAnonCuts ??= [];
+				fork.pendingAnonCuts.push(describeCutEdit(edit));
+			}
+		} else if (edit.kind === "paste") {
+			readRegister(edit.register, fork, edit.lineNum, "throw");
 		}
 	}
 }

package/src/format.ts

@@ -13,40 +13,31 @@ export const HL_FILE_SUFFIX = "]";
 /** Payload sigil for literal body rows. */
 export const HL_PAYLOAD_REPLACE = "+";
 
-/** Hunk-header keyword for concrete line replacement. */
-export const HL_REPLACE_KEYWORD = "SWAP";
-/** Hunk-header keyword for insertion operations. */
-export const HL_INSERT_KEYWORD = "INS";
-/** Insert position keyword for inserting before a concrete line. */
-export const HL_INSERT_BEFORE = "PRE";
-/** Insert position keyword for inserting after a concrete line. */
-export const HL_INSERT_AFTER = "POST";
-/** Insert position keyword for inserting at the start of the file. */
-export const HL_INSERT_HEAD = "HEAD";
-/** Insert position keyword for inserting at the end of the file. */
-export const HL_INSERT_TAIL = "TAIL";
-/** Hunk-header keyword: `SWAP.BLK N:` resolves N to a tree-sitter block range and replaces its span. */
-export const HL_REPLACE_BLOCK_KEYWORD = "SWAP.BLK";
-/** Hunk-header keyword: `INS.BLK.POST N:` inserts after the last line of the tree-sitter block at N. */
-export const HL_INSERT_AFTER_BLOCK_KEYWORD = "INS.BLK.POST";
-/** Hunk-header keyword: `CUT N.=M` captures lines into the clipboard register and deletes them. */
+/** Hunk-header keyword: `PUT` writes content (body rows) or a register at a span or gap. */
+export const HL_PUT_KEYWORD = "PUT";
+/** Hunk-header keyword: `CUT N.=M` / `CUT N*` deletes lines and captures them (anonymous register, or `@name` when given). */
 export const HL_CUT_KEYWORD = "CUT";
-/** Hunk-header keyword: `CUT.BLK N` captures the tree-sitter block at N and deletes its span. */
-export const HL_CUT_BLOCK_KEYWORD = "CUT.BLK";
-/** Hunk-header keyword prefix: `PASTE.PRE|POST N` / `PASTE.HEAD|TAIL` inserts the clipboard. */
-export const HL_PASTE_KEYWORD = "PASTE";
-/** Hunk-header keyword: `PASTE.BLK.POST N` inserts the clipboard after the tree-sitter block at N. */
-export const HL_PASTE_AFTER_BLOCK_KEYWORD = "PASTE.BLK.POST";
 /** File-level keyword: `REM` deletes the whole file named by the section header. */
 export const HL_REM_KEYWORD = "REM";
 /** File-level keyword: `MV DEST` renames/moves the section file to `DEST`. */
 export const HL_MOVE_KEYWORD = "MV";
 export const HL_HEADER_COLON = ":";
 
+/** Gap sigil: `<N` targets the gap before line N (`<1` = head). */
+export const HL_GAP_BEFORE = "<";
+/** Gap sigil: `>N` targets the gap after line N (`>$` = tail). */
+export const HL_GAP_AFTER = ">";
+/** Locator suffix: `N*` extends the anchor to the syntactic block opening at N. */
+export const HL_BLOCK_SUFFIX = "*";
+/** Gap anchor: `$` names the last line, so `>$` is end-of-file. */
+export const HL_EOF_ANCHOR = "$";
+/** Register sigil: `@name` selects a named clipboard register on `PUT`/`CUT`. */
+export const HL_REGISTER_SIGIL = "@";
+
 /** Separator between a hashline file path and its opaque snapshot tag. */
 export const HL_FILE_HASH_SEP = "#";
 
-/** Separator between two line numbers in a range, e.g. `5.=10`. */
+/** Canonical separator between inclusive range endpoints, e.g. `5.=10`. */
 export const HL_RANGE_SEP = ".=";
 
 /** Separator between a line number and displayed line content in hashline mode. */
@@ -62,30 +53,40 @@ export const HL_LINE_RE_RAW = `[1-9]\\d*`;
 /** Capture-group form of {@link HL_LINE_RE_RAW}. */
 export const HL_LINE_CAPTURE_RE_RAW = `(${HL_LINE_RE_RAW})`;
 
-/** Format a concrete replacement hunk header. */
+/** Format a concrete replacement hunk header (`PUT 5.=9:`). */
 export function formatReplaceHeader(start: number, end: number): string {
-	return `${HL_REPLACE_KEYWORD} ${start}${HL_RANGE_SEP}${end}${HL_HEADER_COLON}`;
+	return `${HL_PUT_KEYWORD} ${start}${HL_RANGE_SEP}${end}${HL_HEADER_COLON}`;
 }
 
-/** Format a concrete cut hunk header. */
+/** Format a concrete cut hunk header (`CUT 5.=9`). */
 export function formatCutHeader(start: number, end = start): string {
-	return start === end ? `${HL_CUT_KEYWORD} ${start}` : `${HL_CUT_KEYWORD} ${start}${HL_RANGE_SEP}${end}`;
+	return `${HL_CUT_KEYWORD} ${start}${HL_RANGE_SEP}${end}`;
 }
 
-/** Format an insertion hunk header for a cursor position. */
-export function formatInsertHeader(cursor: Cursor): string {
+/** Format a gap locator for a cursor position (`<5`, `>5`, `<1`, `>$`). */
+export function formatGapLocator(cursor: Cursor): string {
 	switch (cursor.kind) {
 		case "before_anchor":
-			return `${HL_INSERT_KEYWORD}.${HL_INSERT_BEFORE} ${cursor.anchor.line}${HL_HEADER_COLON}`;
+			return `${HL_GAP_BEFORE}${cursor.anchor.line}`;
 		case "after_anchor":
-			return `${HL_INSERT_KEYWORD}.${HL_INSERT_AFTER} ${cursor.anchor.line}${HL_HEADER_COLON}`;
+			return `${HL_GAP_AFTER}${cursor.anchor.line}`;
 		case "bof":
-			return `${HL_INSERT_KEYWORD}.${HL_INSERT_HEAD}${HL_HEADER_COLON}`;
+			return `${HL_GAP_BEFORE}1`;
 		case "eof":
-			return `${HL_INSERT_KEYWORD}.${HL_INSERT_TAIL}${HL_HEADER_COLON}`;
+			return `${HL_GAP_AFTER}${HL_EOF_ANCHOR}`;
 	}
 }
 
+/** Format an insertion hunk header for a cursor position (`PUT <5:`, `PUT >$:`). */
+export function formatInsertHeader(cursor: Cursor): string {
+	return `${HL_PUT_KEYWORD} ${formatGapLocator(cursor)}${HL_HEADER_COLON}`;
+}
+
+/** Format a register reference (`@name`). */
+export function formatRegister(name: string): string {
+	return `${HL_REGISTER_SIGIL}${name}`;
+}
+
 /** Number of hex characters in a content-derived file-hash tag. */
 export const HL_FILE_HASH_LENGTH = 4;
 /** Canonical uppercase hexadecimal content-hash tag carried by a hashline section header. */

package/src/grammar.lark

@@ -7,20 +7,21 @@ file_header: "[" filename "#" file_hash "]" LF
 file_hash: /[0-9A-F]{4}/
 filename: /[^#\r\n]+/
 
-hunk: swap_hunk | ins_hunk | cut_hunk | paste_hunk | rem_hunk | mv_hunk
-swap_hunk: "SWAP " header_range ":" LF body*
-         | "SWAP.BLK " LID ":" LF body+
-ins_hunk: "INS." pos ":" LF body+
-cut_hunk: "CUT" target LF
-paste_hunk: "PASTE." pos LF
+hunk: put_hunk | cut_hunk | rem_hunk | mv_hunk
+put_hunk: "PUT " put_locator ":" LF body+
+        | "PUT " put_locator register LF
+        | "PUT " gap_locator LF
+cut_hunk: "CUT " cut_locator register? LF
 rem_hunk: "REM" LF
-mv_hunk: "MV " filename LF body*
+mv_hunk: "MV " filename LF
 
-target: " " header_range | ".BLK " LID
-pos: "PRE " LID | "POST " LID | "BLK.POST " LID | "HEAD" | "TAIL"
-body: "+" /(.*)/ LF
+put_locator: range | LID "*" | gap_locator
+cut_locator: range | LID "*"
+gap_locator: "<" LID | ">" LID | ">" LID "*" | ">$"
+register: " @" /[A-Za-z0-9_-]+/
 
-header_range: LID ".=" LID
+range: LID ".=" LID
 LID: /[1-9]\d*/
+body: "+" /(.*)/ LF
 
 %import common.LF

package/src/input.ts

@@ -305,11 +305,11 @@ export class PatchSection {
 	 */
 	get hasAnchorScopedEdit(): boolean {
 		return this.edits.some(edit => {
-			if (edit.kind === "delete") return true;
-			// A `replace_block N:` edit is anchored to concrete content on line N.
-			if (edit.kind === "block") return true;
-			// A `CUT` range reads concrete content.
-			if (edit.kind === "cut") return true;
+			if (edit.kind === "delete" || edit.kind === "block" || edit.kind === "cut") return true;
+			if (edit.kind === "paste") {
+				if (edit.at.kind === "span") return true;
+				return edit.at.cursor.kind === "before_anchor" || edit.at.cursor.kind === "after_anchor";
+			}
 			return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor";
 		});
 	}
@@ -318,11 +318,7 @@ export class PatchSection {
 	collectAnchorLines(): readonly number[] {
 		const lines = new Set<number>();
 		for (const edit of this.edits) {
-			if (edit.kind === "delete") {
-				lines.add(edit.anchor.line);
-				continue;
-			}
-			if (edit.kind === "block") {
+			if (edit.kind === "delete" || edit.kind === "block") {
 				lines.add(edit.anchor.line);
 				continue;
 			}
@@ -330,6 +326,14 @@ export class PatchSection {
 				for (let line = edit.range.start.line; line <= edit.range.end.line; line++) lines.add(line);
 				continue;
 			}
+			if (edit.kind === "paste") {
+				if (edit.at.kind === "span") {
+					for (let line = edit.at.range.start.line; line <= edit.at.range.end.line; line++) lines.add(line);
+				} else if (edit.at.cursor.kind === "before_anchor" || edit.at.cursor.kind === "after_anchor") {
+					lines.add(edit.at.cursor.anchor.line);
+				}
+				continue;
+			}
 			if (edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor") {
 				lines.add(edit.cursor.anchor.line);
 			}