From f96f08f644eb44d614783611c685bfeb487006f2 Mon Sep 17 00:00:00 2001 From: Marat K Date: Mon, 26 Oct 2026 22:54:51 +0100 Subject: [PATCH 1/2] feat(native): add source insertion, removal and key renaming Expose textual and literal-segment mutation APIs through the verified Rust core, require the new ABI 2 symbols, and free copied native buffers in finally. Add native regression coverage and immutable core-pin checks. Pure operations remain unfinished in this draft. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 58 ++++++ Cargo.toml | 2 +- crates/cabi/src/lib.rs | 8 +- lib/src/main/java/lang/ktav/Ktav.java | 177 +++++++++++++++++- .../java/lang/ktav/internal/NativeLib.java | 89 +++++++++ .../java/lang/ktav/NativeMutationTest.java | 135 +++++++++++++ 6 files changed, 462 insertions(+), 7 deletions(-) create mode 100644 lib/src/test/java/lang/ktav/NativeMutationTest.java diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 969b1ed..11a9090 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -67,9 +67,49 @@ jobs: - uses: gradle/actions/setup-gradle@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.x' + - name: Build native library run: cargo build --release -p ktav-cabi + - name: Verify generated lockfile uses the pinned core revision + shell: bash + run: | + python - <<'PY' + import tomllib + with open('Cargo.lock', 'rb') as source: + packages = tomllib.load(source)['package'] + core = [package for package in packages if package['name'] == 'ktav'] + expected_source = 'git+https://github.com/ktav-lang/rust?rev=861c64a8378242b87b66b7d7bfeb119996ce3643#861c64a8378242b87b66b7d7bfeb119996ce3643' + if len(core) != 1 or core[0].get('source') != expected_source: + raise SystemExit(f'expected exactly one ktav from pinned git revision; found {core!r}') + print('generated lockfile resolves ktav from the pinned core revision') + PY + + - name: Verify required native ABI symbols + if: runner.os == 'Linux' + shell: bash + run: | + set -euo pipefail + nm -D --defined-only target/release/libktav_cabi.so | awk '{print $3}' | python -c ' + import sys + required = { + "ktav_loads", "ktav_loads_strict", "ktav_dumps", "ktav_dumps_force_strings", + "ktav_emit_canonical", "ktav_format", "ktav_canonical_from_source", + "ktav_edit_value", "ktav_edit_value_segments", "ktav_insert_value", + "ktav_insert_value_segments", "ktav_remove_value", "ktav_remove_value_segments", + "ktav_rename_key", "ktav_rename_key_segments", "ktav_free", "ktav_version", + "ktav_abi_version", + } + exported = set(sys.stdin.read().split()) + missing = sorted(required - exported) + if missing: + raise SystemExit("missing native ABI symbols: " + ", ".join(missing)) + print("required native ABI symbols are exported") + ' + - name: Gradle test run: ./gradlew :lib:test --no-daemon --stacktrace @@ -244,9 +284,27 @@ jobs: - uses: gradle/actions/setup-gradle@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.x' + - name: Build DEBUG native library run: cargo build -p ktav-cabi + - name: Verify generated lockfile uses the pinned core revision + shell: bash + run: | + python - <<'PY' + import tomllib + with open('Cargo.lock', 'rb') as source: + packages = tomllib.load(source)['package'] + core = [package for package in packages if package['name'] == 'ktav'] + expected_source = 'git+https://github.com/ktav-lang/rust?rev=861c64a8378242b87b66b7d7bfeb119996ce3643#861c64a8378242b87b66b7d7bfeb119996ce3643' + if len(core) != 1 or core[0].get('source') != expected_source: + raise SystemExit(f'expected exactly one ktav from pinned git revision; found {core!r}') + print('generated lockfile resolves ktav from the pinned core revision') + PY + - name: Empty-input tests against the real debug artifact env: KTAV_LIB_PATH: ${{ github.workspace }}/target/debug/libktav_cabi.so diff --git a/Cargo.toml b/Cargo.toml index aa95f96..f33af93 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,7 +11,7 @@ rust-version = "1.71" [workspace.dependencies] # Подготовка 0.9: immutable core pin с source-edit и ABI 2; пакет ещё не опубликован. -ktav = { git = "https://github.com/ktav-lang/rust", rev = "447a00bd012e8d3f347c7e1eb59c3f0d9a78332f" } +ktav = { git = "https://github.com/ktav-lang/rust", rev = "861c64a8378242b87b66b7d7bfeb119996ce3643" } serde = { version = "1", features = ["derive"] } serde_json = { version = "1", features = ["preserve_order"] } indexmap = "2" diff --git a/crates/cabi/src/lib.rs b/crates/cabi/src/lib.rs index a0ca6d7..69af4a4 100644 --- a/crates/cabi/src/lib.rs +++ b/crates/cabi/src/lib.rs @@ -3,8 +3,12 @@ //! //! The whole exported surface — `ktav_loads`, `ktav_loads_strict`, //! `ktav_dumps`, `ktav_dumps_force_strings`, `ktav_emit_canonical`, -//! `ktav_format`, `ktav_canonical_from_source`, `ktav_free`, -//! `ktav_version` and `ktav_abi_version` — is expanded by the +//! `ktav_format`, `ktav_canonical_from_source`, `ktav_edit_value`, +//! `ktav_edit_value_segments`, `ktav_insert_value`, +//! `ktav_insert_value_segments`, `ktav_remove_value`, +//! `ktav_remove_value_segments`, `ktav_rename_key`, +//! `ktav_rename_key_segments`, `ktav_free`, `ktav_version` and +//! `ktav_abi_version` — is expanded by the //! `ktav::declare_cabi!()` macro (ktav's `cabi` feature); this crate //! carries no logic of its own. The symbols are expanded here, in the //! cdylib's own crate, because symbols defined in a dependency rlib diff --git a/lib/src/main/java/lang/ktav/Ktav.java b/lib/src/main/java/lang/ktav/Ktav.java index 241e04f..7f4db62 100644 --- a/lib/src/main/java/lang/ktav/Ktav.java +++ b/lib/src/main/java/lang/ktav/Ktav.java @@ -279,6 +279,170 @@ public static String editValueSegments(byte[] src, true); } + /** Insert a value at a textual dotted path. The final segment is a new Object key. */ + public static String insertValue(String src, String path, Value value) { + return sourceEdit(bytes(src, "src"), bytes(path, "path"), value, null, + "insert", false); + } + + /** Byte-level variant of {@link #insertValue(String, String, Value)}. */ + public static String insertValue(byte[] src, String path, Value value) { + return sourceEdit(src, bytes(path, "path"), value, null, "insert", false); + } + + /** Insert a value using decoded literal path segments. */ + public static String insertValueSegments(String src, List segments, + Value value) { + return sourceEdit(bytes(src, "src"), WireJson.encodePath(segments), + value, null, "insert", true); + } + + /** Byte-level variant of {@link #insertValueSegments(String, List, Value)}. */ + public static String insertValueSegments(byte[] src, List segments, + Value value) { + return sourceEdit(src, WireJson.encodePath(segments), value, null, + "insert", true); + } + + /** Remove the value addressed by a textual dotted path. */ + public static String removeValue(String src, String path) { + return sourceEdit(bytes(src, "src"), bytes(path, "path"), null, null, + "remove", false); + } + + /** Byte-level variant of {@link #removeValue(String, String)}. */ + public static String removeValue(byte[] src, String path) { + return sourceEdit(src, bytes(path, "path"), null, null, "remove", false); + } + + /** Remove the value addressed by decoded literal path segments. */ + public static String removeValueSegments(String src, List segments) { + return sourceEdit(bytes(src, "src"), WireJson.encodePath(segments), null, + null, "remove", true); + } + + /** Byte-level variant of {@link #removeValueSegments(String, List)}. */ + public static String removeValueSegments(byte[] src, List segments) { + return sourceEdit(src, WireJson.encodePath(segments), null, null, + "remove", true); + } + + /** Rename the final addressed key; {@code newKey} is a literal decoded key. */ + public static String renameKey(String src, String path, String newKey) { + return sourceEdit(bytes(src, "src"), bytes(path, "path"), null, + bytes(newKey, "newKey"), "rename", false); + } + + /** Byte-level variant of {@link #renameKey(String, String, String)}. */ + public static String renameKey(byte[] src, String path, String newKey) { + return sourceEdit(src, bytes(path, "path"), null, bytes(newKey, "newKey"), + "rename", false); + } + + /** Rename the final addressed key using decoded literal path segments. */ + public static String renameKeySegments(String src, List segments, + String newKey) { + return sourceEdit(bytes(src, "src"), WireJson.encodePath(segments), null, + bytes(newKey, "newKey"), "rename", true); + } + + /** Byte-level variant of {@link #renameKeySegments(String, List, String)}. */ + public static String renameKeySegments(byte[] src, List segments, + String newKey) { + return sourceEdit(src, WireJson.encodePath(segments), null, + bytes(newKey, "newKey"), "rename", true); + } + + private static String sourceEdit(byte[] src, byte[] path, Value value, + byte[] newKey, String operation, boolean segments) { + if (src == null) { + throw new NullPointerException("src"); + } + if (path == null) { + throw new NullPointerException("path"); + } + if ("insert".equals(operation) && value == null) { + throw new NullPointerException("value"); + } + if ("rename".equals(operation) && newKey == null) { + throw new NullPointerException("newKey"); + } + byte[] payload = "insert".equals(operation) ? WireJson.encode(value) : null; + NativeLib lib = NativeLib.get(); + try (Memory srcMem = new Memory(Math.max(1, src.length)); + Memory pathMem = new Memory(Math.max(1, path.length)); + Memory valueMem = payload == null ? null + : new Memory(Math.max(1, payload.length)); + Memory keyMem = newKey == null ? null + : new Memory(Math.max(1, newKey.length))) { + if (src.length > 0) { + srcMem.write(0, src, 0, src.length); + } + if (path.length > 0) { + pathMem.write(0, path, 0, path.length); + } + if (payload != null && payload.length > 0) { + valueMem.write(0, payload, 0, payload.length); + } + if (newKey != null && newKey.length > 0) { + keyMem.write(0, newKey, 0, newKey.length); + } + + PointerByReference outBuf = new PointerByReference(); + LongByReference outLen = new LongByReference(); + PointerByReference outErr = new PointerByReference(); + LongByReference outErrLen = new LongByReference(); + final int rc; + try { + if ("remove".equals(operation)) { + rc = segments + ? lib.ktav_remove_value_segments(srcMem, src.length, + pathMem, path.length, outBuf, outLen, + outErr, outErrLen) + : lib.ktav_remove_value(srcMem, src.length, pathMem, + path.length, outBuf, outLen, outErr, outErrLen); + } else if ("rename".equals(operation)) { + rc = segments + ? lib.ktav_rename_key_segments(srcMem, src.length, + pathMem, path.length, keyMem, newKey.length, + outBuf, outLen, outErr, outErrLen) + : lib.ktav_rename_key(srcMem, src.length, pathMem, + path.length, keyMem, newKey.length, + outBuf, outLen, outErr, outErrLen); + } else { + rc = segments + ? lib.ktav_insert_value_segments(srcMem, src.length, + pathMem, path.length, valueMem, payload.length, + outBuf, outLen, outErr, outErrLen) + : lib.ktav_insert_value(srcMem, src.length, pathMem, + path.length, valueMem, payload.length, + outBuf, outLen, outErr, outErrLen); + } + } catch (LinkageError e) { + throw missingSourceEditSymbol(e); + } + + if (rc != 0) { + byte[] error = copyAndFreeBytes(lib, outErr.getValue(), + outErrLen.getValue()); + if (error.length == 0) { + throw new KtavException("native call failed with code " + rc); + } + throw KtavException.fromEnvelope(ErrorEnvelope.parse(error)); + } + return new String(copyAndFreeBytes(lib, outBuf.getValue(), + outLen.getValue()), StandardCharsets.UTF_8); + } + } + + private static KtavException missingSourceEditSymbol(LinkageError cause) { + return new KtavException( + "the loaded ktav_cabi native library does not provide the" + + " source-mutation entry point; a library with the" + + " required ABI-2 symbol is required", + cause); + } + private static byte[] bytes(String s, String arg) { if (s == null) { throw new NullPointerException(arg); @@ -413,12 +577,17 @@ private static byte[] callNative(NativeOp op, byte[] input) { } private static byte[] copyAndFreeBytes(NativeLib lib, Pointer ptr, long len) { - if (ptr == null || len <= 0) { + if (ptr == null) { return new byte[0]; } - byte[] out = ptr.getByteArray(0, toIntLen(len)); - lib.ktav_free(ptr, len); - return out; + try { + if (len <= 0) { + return new byte[0]; + } + return ptr.getByteArray(0, toIntLen(len)); + } finally { + lib.ktav_free(ptr, len); + } } private static int toIntLen(long len) { diff --git a/lib/src/main/java/lang/ktav/internal/NativeLib.java b/lib/src/main/java/lang/ktav/internal/NativeLib.java index cf7a837..2d0ca0f 100644 --- a/lib/src/main/java/lang/ktav/internal/NativeLib.java +++ b/lib/src/main/java/lang/ktav/internal/NativeLib.java @@ -2,6 +2,7 @@ import com.sun.jna.Library; import com.sun.jna.Native; +import com.sun.jna.NativeLibrary; import com.sun.jna.Pointer; import com.sun.jna.ptr.LongByReference; import com.sun.jna.ptr.PointerByReference; @@ -96,6 +97,74 @@ int ktav_edit_value_segments( PointerByReference outErr, LongByReference outErrLen); + int ktav_insert_value( + Pointer src, + long srcLen, + Pointer path, + long pathLen, + Pointer replacement, + long replacementLen, + PointerByReference outBuf, + LongByReference outLen, + PointerByReference outErr, + LongByReference outErrLen); + + int ktav_insert_value_segments( + Pointer src, + long srcLen, + Pointer path, + long pathLen, + Pointer replacement, + long replacementLen, + PointerByReference outBuf, + LongByReference outLen, + PointerByReference outErr, + LongByReference outErrLen); + + int ktav_remove_value( + Pointer src, + long srcLen, + Pointer path, + long pathLen, + PointerByReference outBuf, + LongByReference outLen, + PointerByReference outErr, + LongByReference outErrLen); + + int ktav_remove_value_segments( + Pointer src, + long srcLen, + Pointer path, + long pathLen, + PointerByReference outBuf, + LongByReference outLen, + PointerByReference outErr, + LongByReference outErrLen); + + int ktav_rename_key( + Pointer src, + long srcLen, + Pointer path, + long pathLen, + Pointer newKey, + long newKeyLen, + PointerByReference outBuf, + LongByReference outLen, + PointerByReference outErr, + LongByReference outErrLen); + + int ktav_rename_key_segments( + Pointer src, + long srcLen, + Pointer path, + long pathLen, + Pointer newKey, + long newKeyLen, + PointerByReference outBuf, + LongByReference outLen, + PointerByReference outErr, + LongByReference outErrLen); + void ktav_free(Pointer ptr, long len); String ktav_version(); @@ -126,9 +195,29 @@ private static NativeLib loadSingleton() { + " (source-edit entry points need the 0.9" + " native library): " + path); } + NativeLibrary symbols = NativeLibrary.getInstance(path); + // Keep this handle open: the JNA proxy uses the same loaded library. + requireSymbol(symbols, "ktav_edit_value"); + requireSymbol(symbols, "ktav_edit_value_segments"); + requireSymbol(symbols, "ktav_insert_value"); + requireSymbol(symbols, "ktav_insert_value_segments"); + requireSymbol(symbols, "ktav_remove_value"); + requireSymbol(symbols, "ktav_remove_value_segments"); + requireSymbol(symbols, "ktav_rename_key"); + requireSymbol(symbols, "ktav_rename_key_segments"); return lib; } + private static void requireSymbol(NativeLibrary library, String name) { + try { + library.getFunction(name); + } catch (UnsatisfiedLinkError e) { + throw new IllegalStateException( + "ktav_cabi is missing required ABI-2 export " + + name + ": " + library.getName(), e); + } + } + private Holder() { } } diff --git a/lib/src/test/java/lang/ktav/NativeMutationTest.java b/lib/src/test/java/lang/ktav/NativeMutationTest.java new file mode 100644 index 0000000..1d84838 --- /dev/null +++ b/lib/src/test/java/lang/ktav/NativeMutationTest.java @@ -0,0 +1,135 @@ +package lang.ktav; + +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Test; + +import java.nio.file.Files; +import java.nio.file.Paths; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** Native-only regression port of Rust CABI mutation wrapper cases. */ +final class NativeMutationTest { + @BeforeAll + static void requireBuiltCabi() { + TestPaths.init(); + String debugFlag = System.getenv("KTAV_DEBUG_CABI"); + if (debugFlag != null && debugFlag.matches("(?i)debug")) { + String libPath = System.getenv("KTAV_LIB_PATH"); + assertTrue(libPath != null && Files.isRegularFile(Paths.get(libPath)), + CorpusHarness.CABI_MISSING + " (KTAV_LIB_PATH=" + libPath + ")"); + } else { + assertTrue(TestPaths.cabiBuilt(), CorpusHarness.CABI_MISSING); + } + } + + private static Value integer(String n) { return new Value.Int(n); } + private static Value string(String s) { return new Value.Str(s); } + + @Test + void insertTextualSegmentsAndBoundaries() { + assertEquals("a: 1\nb: 9007199254740993\n", + Ktav.insertValue("a: 1\n", "b", integer("9007199254740993"))); + assertEquals("a: 1\nb: -0.0\n", + Ktav.insertValueSegments("a: 1\n", List.of("b"), new Value.Flt("-0.0"))); + assertEquals("a: {x: 1, y: two}\n", + Ktav.insertValue("a: {x: 1}\n", "a.y", string("two"))); + assertEquals("a: 1\n\"a.b\": 2\n", + Ktav.insertValue("a: 1\n", "a\\.b", integer("2"))); + assertEquals("## header\nk: v\n", Ktav.insertValue("## header\n", "k", string("v"))); + assertEquals("a: 1\r\nb: v\r\n", Ktav.insertValue("a: 1\r\n", "b", string("v"))); + KtavException collision = assertThrows(KtavException.class, + () -> Ktav.insertValue("a: 1\nb: 2\n", "b", Value.Null.NULL)); + assertEquals("EditAlreadyExists", collision.getError()); + assertNull(collision.getBody()); + assertEquals("EditNotFound", assertThrows(KtavException.class, + () -> Ktav.insertValue("a: 1\n", "b.c", Value.Null.NULL)).getError()); + KtavException invalid = assertThrows(KtavException.class, + () -> Ktav.insertValue("a: 1\n", "a..b", Value.Null.NULL)); + assertEquals("EditInvalidPath", invalid.getError()); + assertEquals("2", invalid.getBody()); + } + + @Test + void removeTextualSegmentsAndArrayBoundaries() { + assertEquals("b: 2\n", Ktav.removeValue("a: 1\nb: 2\n", "a")); + assertEquals("a: [1, 3]\n", + Ktav.removeValueSegments("a: [1, 2, 3]\n", List.of("a", "1"))); + assertEquals("EditNotFound", assertThrows(KtavException.class, + () -> Ktav.removeValue("b: 1\n", "a")).getError()); + assertEquals("EditNotFound", assertThrows(KtavException.class, + () -> Ktav.removeValueSegments("a: 1\n", List.of())).getError()); + + } + + @Test + void renameTextualSegmentsNoopAndCollisions() { + assertEquals("a: 1\nx: 2\n", Ktav.renameKey("a: 1\nb: 2\n", "b", "x")); + assertEquals("a: {w: 1, y: 2}\n", + Ktav.renameKeySegments("a: {x: 1, y: 2}\n", List.of("a", "x"), "w")); + assertEquals("k:: 042\r\n", Ktav.renameKey("k:: 042\r\n", "k", "k")); + KtavException collision = assertThrows(KtavException.class, + () -> Ktav.renameKey("a: 1\nb: 2\n", "a", "b")); + assertEquals("EditAlreadyExists", collision.getError()); + assertNull(collision.getBody()); + assertEquals("ключ: 1\n", Ktav.renameKey("a: 1\n", "a", "ключ")); + assertEquals("k: 1\nx\\\\y: 2\n", Ktav.insertValue("k: 1\n", "x\\\\y", integer("2"))); + assertEquals("m: 1\n", Ktav.renameKeySegments("x\\\\y: 1\n", List.of("x\\y"), "m")); + } + + @Test + void sourceFirstForMalformedUtf8AndInvalidPathAcrossOperations() { + byte[] invalidUtf8 = new byte[] {'a', ':', ' ', (byte) 0xff}; + assertSourceFirst(() -> Ktav.insertValue(invalidUtf8, "\\q", Value.Null.NULL)); + assertSourceFirst(() -> Ktav.insertValueSegments(invalidUtf8, List.of(), Value.Null.NULL)); + assertSourceFirst(() -> Ktav.removeValue(invalidUtf8, "\\q")); + assertSourceFirst(() -> Ktav.removeValueSegments(invalidUtf8, List.of())); + assertSourceFirst(() -> Ktav.renameKey(invalidUtf8, "\\q", "x")); + assertSourceFirst(() -> Ktav.renameKeySegments(invalidUtf8, List.of(), "x")); + } + + private interface Call { void run(); } + + private static void assertSourceFirst(Call call) { + KtavException e = assertThrows(KtavException.class, call::run); + assertEquals("InvalidUtf8", e.getError()); + assertEquals(Long.valueOf(1), e.getLine()); + assertEquals(Long.valueOf(3), e.getSpanStart()); + assertEquals(Long.valueOf(4), e.getSpanEnd()); + } + + @Test + void sourceOffsetIsUtf8ByteBasedAndMutationErrorsHaveExactBodies() { + KtavException invalid = assertThrows(KtavException.class, + () -> Ktav.insertValue("я: 1\n", "я..x", Value.Null.NULL)); + assertEquals("EditInvalidPath", invalid.getError()); + assertEquals("3", invalid.getBody()); + assertNull(invalid.getLine()); + KtavException collision = assertThrows(KtavException.class, + () -> Ktav.renameKey("a: 1\nb: 2\n", "a", "b")); + assertEquals("EditAlreadyExists", collision.getError()); + assertNull(collision.getBody()); + } + + @Test + void losslessCommentsBomCrlfAndEmptySource() { + assertEquals("a: 1\n## tail\nb: v\n", + Ktav.insertValue("a: 1\n## tail\n", "b", string("v"))); + String bomCrlf = "\uFEFFk:: +1\r\n"; + assertEquals(bomCrlf, Ktav.renameKey(bomCrlf, "k", "k")); + assertEquals("k: v", Ktav.insertValue("", "k", string("v"))); + assertEquals("k: v", Ktav.insertValueSegments("", List.of("k"), string("v"))); + assertEquals("EditNotFound", assertThrows(KtavException.class, + () -> Ktav.removeValue("", "k")).getError()); + assertEquals("EditNotFound", assertThrows(KtavException.class, + () -> Ktav.removeValueSegments("", List.of("k"))).getError()); + assertEquals("EditNotFound", assertThrows(KtavException.class, + () -> Ktav.renameKey("", "k", "x")).getError()); + assertEquals("EditNotFound", assertThrows(KtavException.class, + () -> Ktav.renameKeySegments("", List.of("k"), "x")).getError()); + } +} From bd0d3d19f6635356179e11ea7268ebb3646fe12f Mon Sep 17 00:00:00 2001 From: Marat K Date: Tue, 27 Oct 2026 12:46:22 +0100 Subject: [PATCH 2/2] feat(pure): add lossless source mutations Implement insertion, removal, and literal-key renaming with textual and decoded paths. Verify intended semantic trees after source splices and cover layout, comments, BOM, mixed line endings, and no-prune removal. Pin the corrected core and document the shared EN/RU/ZH contract. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 6 +- CHANGELOG.md | 2 + Cargo.toml | 2 +- README.md | 54 ++- docs/ru/CHANGELOG.ru.md | 2 + docs/ru/README.ru.md | 63 ++- docs/zh/CHANGELOG.zh.md | 2 + docs/zh/README.zh.md | 46 +- .../main/java/lang/ktav/pure/EditError.java | 6 + .../main/java/lang/ktav/pure/EditSplice.java | 301 +++++++++++++ .../main/java/lang/ktav/pure/EditTree.java | 19 +- lib/src/main/java/lang/ktav/pure/Layout.java | 2 +- .../main/java/lang/ktav/pure/PureKtav.java | 127 ++++++ .../java/lang/ktav/pure/RemoveSplice.java | 253 +++++++++++ .../java/lang/ktav/pure/RenameSplice.java | 106 +++++ .../java/lang/ktav/PureInsertValueTest.java | 426 ++++++++++++++++++ .../java/lang/ktav/PureRemoveRenameTest.java | 219 +++++++++ root-docs/CHANGELOG/unreleased/body-1.md | 6 + root-docs/README/editing/body-1.md | 14 + root-docs/README/editing/body-2.md | 114 +++-- root-docs/README/pure-backend/body-1.md | 13 + root-docs/README/pure-backend/body-2.md | 36 +- 22 files changed, 1690 insertions(+), 129 deletions(-) create mode 100644 lib/src/main/java/lang/ktav/pure/RemoveSplice.java create mode 100644 lib/src/main/java/lang/ktav/pure/RenameSplice.java create mode 100644 lib/src/test/java/lang/ktav/PureInsertValueTest.java create mode 100644 lib/src/test/java/lang/ktav/PureRemoveRenameTest.java diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 11a9090..f5a8fc6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -82,7 +82,7 @@ jobs: with open('Cargo.lock', 'rb') as source: packages = tomllib.load(source)['package'] core = [package for package in packages if package['name'] == 'ktav'] - expected_source = 'git+https://github.com/ktav-lang/rust?rev=861c64a8378242b87b66b7d7bfeb119996ce3643#861c64a8378242b87b66b7d7bfeb119996ce3643' + expected_source = 'git+https://github.com/ktav-lang/rust?rev=8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910#8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910' if len(core) != 1 or core[0].get('source') != expected_source: raise SystemExit(f'expected exactly one ktav from pinned git revision; found {core!r}') print('generated lockfile resolves ktav from the pinned core revision') @@ -186,6 +186,8 @@ jobs: --tests "lang.ktav.PureNoNativeTest" --tests "lang.ktav.CorpusGuardMutationTest" --tests "lang.ktav.PureWhitespaceTest" + --tests "lang.ktav.PureInsertValueTest" + --tests "lang.ktav.PureRemoveRenameTest" - name: Upload test reports if: failure() @@ -299,7 +301,7 @@ jobs: with open('Cargo.lock', 'rb') as source: packages = tomllib.load(source)['package'] core = [package for package in packages if package['name'] == 'ktav'] - expected_source = 'git+https://github.com/ktav-lang/rust?rev=861c64a8378242b87b66b7d7bfeb119996ce3643#861c64a8378242b87b66b7d7bfeb119996ce3643' + expected_source = 'git+https://github.com/ktav-lang/rust?rev=8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910#8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910' if len(core) != 1 or core[0].get('source') != expected_source: raise SystemExit(f'expected exactly one ktav from pinned git revision; found {core!r}') print('generated lockfile resolves ktav from the pinned core revision') diff --git a/CHANGELOG.md b/CHANGELOG.md index cbbbdad..2eae786 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,8 @@ itself — for the latter see ## Unreleased +- Add pure-backend `insertValue` / `insertValueSegments`, `removeValue` / `removeValueSegments`, and `renameKey` / `renameKeySegments`, matching the native source-edit APIs. Insert requires an existing Object parent; remove retains empty ancestors; rename preserves value and order. Successful splices verify the intended tree, and unsafe source shapes fail with `EditUnsupported`. Insert/rename collisions report `EditAlreadyExists`. These APIs prepare 0.9; package versions are unchanged. + ## 0.8.1 — 2026-10-22 ### Added diff --git a/Cargo.toml b/Cargo.toml index f33af93..3accd2c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,7 +11,7 @@ rust-version = "1.71" [workspace.dependencies] # Подготовка 0.9: immutable core pin с source-edit и ABI 2; пакет ещё не опубликован. -ktav = { git = "https://github.com/ktav-lang/rust", rev = "861c64a8378242b87b66b7d7bfeb119996ce3643" } +ktav = { git = "https://github.com/ktav-lang/rust", rev = "8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910" } serde = { version = "1", features = ["derive"] } serde_json = { version = "1", features = ["preserve_order"] } indexmap = "2" diff --git a/README.md b/README.md index 8f10cf5..d7bca0d 100644 --- a/README.md +++ b/README.md @@ -200,22 +200,34 @@ equal to the current value is a byte-identical no-op, even for noncanonical scalar spellings. Paths are dotted (`key1.key2.0.key4`); inside a segment `\.` is a -literal dot and `\\` a literal backslash. `editValueSegments` takes -already-decoded literal segments instead — a numeric segment is a -string key inside an object and a zero-based index inside an array. -There is no create, remove, or rename: only replacement of an existing -value. - -Errors are structured: `EditInvalidPath` (body: the UTF-8 byte offset -inside the path argument where the defect is), `EditNotFound` (missing -key, out-of-bounds index, descent through a scalar, empty segments list), and -`EditUnsupported` (body: the reason — e.g. a noncontiguous -dotted-key/reopen target, a structural replacement that would drop -interior comment lines, or a value without a lossless representation -in the target context). Source-level problems still surface as the ordinary parse -envelopes. The pure backend exposes the same operations as -`PureKtav.editValue` / `PureKtav.editValueSegments` with identical -output. +literal dot and `\\` a literal backslash. The `*Segments` variants take +already-decoded literal segments: numeric segments are Object keys or +zero-based Array indexes, depending on the parent. + +Both `Ktav` and standalone `PureKtav` provide `insertValue`, +`removeValue`, and `renameKey`, plus their `*Segments` variants, with +String and byte-array sources. Insertion creates only a new final key +under an existing Object parent: no overwrite, implicit parents, or +Array insertion. Removal deletes an existing value/subtree or Array +element, shifts remaining elements, and never prunes empty ancestors. +Renaming changes only the final Object key to a literal name, preserving +value and order; the same name is a byte-identical no-op. Array indexes +cannot be renamed. Replacement still changes only an existing value. + +Edits splice source ranges rather than serialize the whole document. +Every success is reparsed and checked against the intended tree; +untouched bytes, comments, BOM, EOL/EOF conventions, and key spelling +remain unchanged. Inline layout expands only where needed for multiline +values, growth beyond max(100 Unicode scalars, original line width), or +String readability (at least four escapes and 25% overhead). Unsupported +source shapes fail explicitly rather than returning corrupted text. + +Errors: `EditInvalidPath` (body: UTF-8 path byte offset), `EditNotFound` +(missing target/parent, scalar descent, invalid Array index, empty decoded +path), `EditAlreadyExists` (insert or rename collision), and +`EditUnsupported` (body: reason, including noncontiguous dotted targets +or removal of a compound containing comments). Source parse errors win +over edit validation. Pure mode has no native dependency or fallback. ### Source-edit cookbook @@ -483,9 +495,15 @@ implementation("io.github.ktav-lang:ktav:0.8.1") { isTransitive = false } For Maven, exclude both `net.java.dev.jna:jna` and `com.fasterxml.jackson.core:jackson-core`; alternatively, use the library JAR directly. Pure-only runtime use requires JDK 17 and no third-party runtime libraries. Pure success and error paths use no JNA, Jackson, JUnit, native code, WASM, subprocesses, network access, or fallback. Native backend use requires its dependencies; retain normal dependency resolution for it. -The facade mirrors `Ktav` operation-for-operation and is designed to +The facade mirrors the shared operations of `Ktav` and is designed to produce the same `Value` tree and the same `KtavException` envelopes, -so code written against one backend reads unchanged against the other. There is no +so code written against one backend reads unchanged against the other +for those operations. Source editing includes replacement, insertion, +removal, and literal-key renaming, with textual and decoded-segment paths. +Successful edits preserve untouched source and verify the intended tree; +unsupported source shapes fail with `EditUnsupported`. Insert and rename +collisions report `EditAlreadyExists`. See the source-edit contract above. +There is no global backend switch: you choose a backend explicitly by calling `Ktav` (native) or `PureKtav` (pure). diff --git a/docs/ru/CHANGELOG.ru.md b/docs/ru/CHANGELOG.ru.md index 27491b9..185229f 100644 --- a/docs/ru/CHANGELOG.ru.md +++ b/docs/ru/CHANGELOG.ru.md @@ -23,6 +23,8 @@ ## Unreleased +- Добавлены чистые `insertValue` / `insertValueSegments`, `removeValue` / `removeValueSegments` и `renameKey` / `renameKeySegments`, соответствующие нативному API. Вставка требует существующего Object-родителя, удаление сохраняет пустых предков, переименование сохраняет значение и порядок. Успешный сплайс проверяет ожидаемое дерево; небезопасная форма исходника даёт `EditUnsupported`. Коллизии вставки/переименования — `EditAlreadyExists`. Это подготовка 0.9; версии пакетов не изменены. + ## 0.8.1 — 2026-10-22 ### Добавлено diff --git a/docs/ru/README.ru.md b/docs/ru/README.ru.md index ec9f55e..6588744 100644 --- a/docs/ru/README.ru.md +++ b/docs/ru/README.ru.md @@ -202,23 +202,36 @@ String out = Ktav.editValue("port: 8080\nhost: db\n", "port", равная текущему значению, — byte-identical no-op даже для неканонических написаний скаляров. -Пути — через точку (`key1.key2.0.key4`); внутри сегмента `\.` — -literal точка, `\\` — literal backslash. `editValueSegments` принимает -уже декодированные literal-сегменты: числовой сегмент — это ключ -внутри объекта и zero-based индекс внутри массива. Создание, удаление -и переименование не поддерживаются — только замена существующего -значения. - -Ошибки структурированы: `EditInvalidPath` (body: UTF-8 byte offset -внутри аргумента пути, где обнаружен дефект), `EditNotFound` -(отсутствующий ключ, индекс вне диапазона, спуск через скаляр, пустой -список сегментов) и `EditUnsupported` (body: причина — например noncontiguous-цель -из dotted-ключей и reopen, структурная замена, которая потеряла бы -комментарии внутри цели, или значение без lossless-представления в контексте цели). -Проблемы самого исходника по-прежнему приходят обычными parse -envelope'ами. Pure-бэкенд предоставляет те же операции — -`PureKtav.editValue` / `PureKtav.editValueSegments` — с идентичным -выводом. +Пути разделены точками (`key1.key2.0.key4`); внутри сегмента `\.` — +буквальная точка, `\\` — обратная косая черта. Варианты `*Segments` +принимают декодированные буквальные сегменты: числовой сегмент — ключ +Object либо индекс Array с нуля в зависимости от родителя. + +`Ktav` и самостоятельный `PureKtav` предоставляют `insertValue`, +`removeValue`, `renameKey` и варианты `*Segments` для String и byte[]. +Вставка создаёт только новый конечный ключ существующего Object: +без перезаписи, неявных родителей или вставки в Array. Удаление убирает +существующее значение/поддерево либо элемент Array, сдвигает оставшиеся +элементы и не удаляет пустых предков. Переименование меняет только +последний ключ Object на буквальное имя, сохраняя значение и порядок; +прежнее имя даёт побайтовый no-op. Индексы Array не переименовываются. +Замена по-прежнему изменяет только существующее значение. + +Правки выполняются сплайсом диапазонов, а не сериализацией документа. +Каждый успешный результат повторно разбирается и сверяется с ожидаемым +деревом; нетронутые байты, комментарии, BOM, EOL/EOF и написание ключей +сохраняются. Inline-раскладка раскрывается лишь по необходимости: +многострочное значение, рост сверх max(100 Unicode-скаляров, исходная +ширина строки) либо читаемость String (не менее четырёх экранирований +и 25% накладных расходов). Неподдерживаемая форма исходника даёт явный +отказ, а не повреждённый текст. + +Ошибки: `EditInvalidPath` (body: UTF-8 byte offset пути), `EditNotFound` +(нет цели/родителя, спуск через скаляр, неверный индекс Array, пустой +декодированный путь), `EditAlreadyExists` (коллизия вставки/переименования) +и `EditUnsupported` (body: причина, включая несмежную dotted-цель или +удаление контейнера с комментариями). Ошибка разбора исходника имеет +приоритет. Чистому режиму не нужны native-зависимости или fallback. ### Практические примеры правки исходника @@ -487,12 +500,16 @@ implementation("io.github.ktav-lang:ktav:0.8.1") { isTransitive = false } В Maven исключите `net.java.dev.jna:jna` и `com.fasterxml.jackson.core:jackson-core`; альтернативно используйте JAR библиотеки напрямую. Для выполнения только чистого бэкенда нужен JDK 17, сторонние runtime-библиотеки не нужны. Успешные и ошибочные пути чистого бэкенда не используют JNA, Jackson, JUnit, нативный код, WASM, процессы, сеть или fallback. Нативному бэкенду нужны его зависимости; для него сохраняйте обычное разрешение зависимостей. -Фасад повторяет `Ktav` операция в операцию и спроектирован так, чтобы -давать то же дерево `Value` и те же конверты `KtavException`, поэтому -код, написанный против одного бэкенда, против другого читается без -изменений. Глобального -переключателя бэкендов нет: бэкенд выбирается явно — вызовом `Ktav` -(нативный) или `PureKtav` (чистый). +Фасад повторяет общие операции `Ktav` и спроектирован так, чтобы +давать то же дерево `Value` и те же конверты `KtavException`; для этих +операций код можно переносить между бэкендами без изменений. Редактирование +включает замену, вставку, удаление и переименование буквального ключа, +с текстовыми путями и декодированными сегментами. Успех сохраняет нетронутый +исходник и проверяет ожидаемое дерево; неподдерживаемая форма даёт +`EditUnsupported`. Коллизии вставки и переименования — `EditAlreadyExists`. +Контракт редактирования описан выше. Глобального переключателя +бэкендов нет: бэкенд выбирается явно — вызовом `Ktav` (нативный) или +`PureKtav` (чистый). Чистый режим никогда не загружает и не скачивает нативную библиотеку — ни JNA, ни `ktav_cabi`, ни кэш-каталога, ни сети. Это правильный выбор diff --git a/docs/zh/CHANGELOG.zh.md b/docs/zh/CHANGELOG.zh.md index 6cab36a..9d7e4d4 100644 --- a/docs/zh/CHANGELOG.zh.md +++ b/docs/zh/CHANGELOG.zh.md @@ -22,6 +22,8 @@ MINOR 递增视为破坏性变更。 ## Unreleased +- 新增纯后端 `insertValue` / `insertValueSegments`、`removeValue` / `removeValueSegments` 和 `renameKey` / `renameKeySegments`,对应原生源文本编辑 API。插入要求已存在的 Object 父节点,删除保留空祖先,重命名保留值和顺序。成功拼接验证预期树,无法安全处理的源形式返回 `EditUnsupported`;插入或重命名冲突返回 `EditAlreadyExists`。这些 API 为 0.9 做准备,包版本不变。 + ## 0.8.1 — 2026-10-22 ### 新增 diff --git a/docs/zh/README.zh.md b/docs/zh/README.zh.md index c272b6a..e8bdd6d 100644 --- a/docs/zh/README.zh.md +++ b/docs/zh/README.zh.md @@ -190,18 +190,29 @@ inline 包装才会展开,且只展开受影响的分支——未触及的嵌 inline。与当前值相等的替换是字节完全一致的 no-op,即使标量拼写不 规范也一样。 -路径以点分隔(`key1.key2.0.key4`);段内 `\.` 表示字面点号,`\\` -表示字面反斜杠。`editValueSegments` 直接接收已解码的字面段——数字段 -在对象中是字符串键,在数组中是从零开始的索引。不支持创建、删除或重 -命名——只支持替换已存在的值。 - -错误是结构化的:`EditInvalidPath`(body:路径参数中发现缺陷处的 -UTF-8 字节偏移)、`EditNotFound`(缺少键、索引越界、穿过标量下降、 -空路径段列表)和 `EditUnsupported`(body:原因——例如由 dotted 键与 reopen -拼成的非连续目标、会丢失容器内部注释的结构性替换,或无法在目标上下文中 -无损表示的值)。源文本本身的问题仍以普通解析错误 envelope 报告。 -纯 Java 后端提供相同操作——`PureKtav.editValue` / -`PureKtav.editValueSegments`,输出完全一致。 +路径以点分隔(`key1.key2.0.key4`);段内 `\.` 表示字面点号, +`\\` 表示字面反斜杠。`*Segments` 接收已解码的字面段;数字段按父节点 +类型解释为 Object 键或从零开始的 Array 索引。 + +`Ktav` 和独立的 `PureKtav` 均提供 `insertValue`、`removeValue`、 +`renameKey` 及 `*Segments` 变体,支持 String 和字节数组源文本。 +插入仅在已存在的 Object 父节点中创建新的末段键,不覆盖现有键, +不隐式创建父节点,也不插入 Array。删除移除现有值、子树或 Array +元素,后续元素前移,但不裁剪空祖先。重命名仅将末段 Object 键改为 +字面名称,保留值与顺序;名称不变时逐字节不变。不能重命名 Array +索引。替换仍仅修改现有值。 + +编辑拼接源文本范围,不重新序列化整个文档。每个成功结果都会重新 +解析并核对预期树;未触及的字节、注释、BOM、EOL/EOF 约定和键拼写 +保持不变。仅在多行值、增长超过 max(100 个 Unicode 标量,原行宽) +或 String 可读性需要时展开 inline 布局;可读性阈值为至少四个转义 +且开销至少 25%。不支持的源文本形式会明确失败,不返回损坏文本。 + +错误包括 `EditInvalidPath`(body:路径的 UTF-8 字节偏移)、 +`EditNotFound`(目标或父节点不存在、穿过标量、无效 Array 索引、 +空解码路径)、`EditAlreadyExists`(插入或重命名冲突)和 +`EditUnsupported`(body:原因,包括不连续 dotted 目标或删除含注释 +的容器)。源文本解析错误优先。纯模式不依赖原生库,也不会回退。 ### 源文本编辑示例 @@ -463,10 +474,13 @@ implementation("io.github.ktav-lang:ktav:0.8.1") { isTransitive = false } ``` Maven 请同时排除 `net.java.dev.jna:jna` 和 `com.fasterxml.jackson.core:jackson-core`;也可直接使用本库 JAR。纯后端运行需要 JDK 17,不需要第三方运行时库。纯后端的成功和错误路径均不使用 JNA、Jackson、JUnit、原生代码、WASM、子进程、网络或回退。原生后端用法需要其依赖;请为其保留常规依赖解析。 -该门面逐操作镜像 `Ktav`,其设计目标是产出相同的 `Value` 树和相同的 -`KtavException` 信封,因此针对一个后端编写的代码,换到另一个后端 -无需改动。没有全局后端开关:后端通过显式调用选择 —— `Ktav` -(原生)或 `PureKtav`(纯)。 +该门面镜像 `Ktav` 的共享操作,并旨在生成相同的 `Value` 树和 +`KtavException` 信封;对于这些操作,代码可在两个后端之间无修改使用。 +源文本编辑包括替换、插入、删除和字面键重命名,支持文本路径和解码段。 +成功编辑保留未触及的源文本并验证预期树;不支持的源形式返回 +`EditUnsupported`。插入和重命名冲突返回 `EditAlreadyExists`。 +具体编辑契约见上文。没有全局后端 +开关:通过显式调用 `Ktav`(原生)或 `PureKtav`(纯)选择后端。 纯模式从不加载或下载原生库 —— 没有 JNA、没有 `ktav_cabi`、没有缓存 目录、没有网络。它适合离线(air-gapped)环境、没有预编译原生资产的 diff --git a/lib/src/main/java/lang/ktav/pure/EditError.java b/lib/src/main/java/lang/ktav/pure/EditError.java index cf14bd6..c3cf2b9 100644 --- a/lib/src/main/java/lang/ktav/pure/EditError.java +++ b/lib/src/main/java/lang/ktav/pure/EditError.java @@ -21,6 +21,7 @@ final class EditError extends RuntimeException { enum Code { INVALID_PATH, NOT_FOUND, + ALREADY_EXISTS, UNSUPPORTED } @@ -48,6 +49,11 @@ static EditError notFound() { "edit path does not address an existing value"); } + static EditError alreadyExists() { + return new EditError(Code.ALREADY_EXISTS, -1, null, + "Object key already exists"); + } + static EditError unsupported(String reason) { return new EditError(Code.UNSUPPORTED, -1, reason, "no lossless source edit: " + reason); diff --git a/lib/src/main/java/lang/ktav/pure/EditSplice.java b/lib/src/main/java/lang/ktav/pure/EditSplice.java index 1ed3d3c..224af31 100644 --- a/lib/src/main/java/lang/ktav/pure/EditSplice.java +++ b/lib/src/main/java/lang/ktav/pure/EditSplice.java @@ -24,6 +24,274 @@ private EditSplice() { // ── Public entry ──────────────────────────────────────────────────── + static String insert(byte[] b, int bomStart, List segments, Value replacement) { + if (segments.isEmpty()) throw EditError.notFound(); + Value original = PureParser.parse(b, bomStart, false); + List parentPath = segments.subList(0, segments.size() - 1); + String key = segments.get(segments.size() - 1); + Value parent = lookupValue(original, parentPath); + if (parent instanceof Value.Arr) throw EditError.unsupported( + "insertion into an Array is not supported; only Object members can be created"); + if (!(parent instanceof Value.Obj object)) throw EditError.notFound(); + if (object.entries().containsKey(key)) throw EditError.alreadyExists(); + + EditTree.Result tree = EditTree.build(b); + Descend parentLoc = parentPath.isEmpty() + ? new Descend(tree.root, tree.root.inline, false) + : descend(tree.root, parentPath, tree.rootExplicit); + if (parentLoc.node.slot == null && !parentPath.isEmpty()) + throw EditError.unsupported("parent is a noncontiguous value (dotted-key/reopen intermediate); no lossless insertion point exists"); + EditTree.Node node = parentLoc.node; + if (node.kind != EditTree.Node.OBJECT) throw EditError.notFound(); + String result; + int layoutFrom = -1; + int layoutTo = -1; + int layoutInserted = 0; + boolean layoutEligible = false; + + boolean owningInlineBody = node.slot != null + && (node.slot.kind == EditTree.Slot.PAIR || node.slot.kind == EditTree.Slot.ITEM) + && isInlineBody(b, node.slot.b0, node.slot.b1); + if (node.inline || owningInlineBody) { + int[] trimmed; + if (node.slot != null) { + trimmed = Bytes.trim(b, node.slot.b0, node.slot.b1); + } else if (parentPath.isEmpty()) { + int lineStart = bomStart; + int contentStart = -1; + while (lineStart < b.length) { + int lineEnd = lineStart; + while (lineEnd < b.length && b[lineEnd] != '\n' && b[lineEnd] != '\r') lineEnd++; + int[] content = Bytes.trim(b, lineStart, lineEnd); + if (content[0] < content[1] && !(content[1] - content[0] >= 2 + && b[content[0]] == '#' && b[content[0] + 1] == '#')) { + contentStart = content[0]; + break; + } + lineStart = lineEnd; + while (lineStart < b.length && (b[lineStart] == '\n' || b[lineStart] == '\r')) lineStart++; + } + if (contentStart < 0) throw EditError.unsupported("inline Object has no lossless insertion range"); + int lineEnd = contentStart; + while (lineEnd < b.length && b[lineEnd] != '\n' && b[lineEnd] != '\r') lineEnd++; + trimmed = Bytes.trim(b, contentStart, lineEnd); + } else { + throw EditError.unsupported("inline Object has no lossless insertion range"); + } + int end = trimmed[1]; + if (end <= trimmed[0] || b[trimmed[0]] != '{' || b[end - 1] != '}') + throw EditError.unsupported("inline Object has no lossless insertion range"); + String existingInline = Bytes.text(b, trimmed[0], end); + if (existingInline.indexOf('\n') >= 0 || existingInline.indexOf('\r') >= 0) + throw EditError.unsupported("multiline inline Object insertion is unsupported"); + String eol = detectEol(b, trimmed[1]); + int close = end - 1; + int[] trailing = Bytes.trim(b, trimmed[0] + 1, close); + int insertAt = trailing[1]; + boolean trailingComma = insertAt > trimmed[0] + 1 && b[insertAt - 1] == ','; + int slashCount = 0; + if (trailingComma) { + for (int i = insertAt - 2; i >= trimmed[0] + 1 && b[i] == '\\'; i--) slashCount++; + trailingComma = (slashCount & 1) == 0; + } + boolean existingMembers = hasInlineMember(b, trimmed[0] + 1, + trailingComma ? insertAt - 1 : close); + String inlinePair = encodeInsertKeySegment(key) + ": " + inlineBody(replacement, true); + int insertedAt; + String insertion; + int spliceTo; + if (!hasInlineMember(b, trimmed[0] + 1, close)) { + insertedAt = trimmed[0] + 1; + spliceTo = close; + insertion = inlinePair; + } else { + if (trailingComma) { + insertedAt = insertAt; + spliceTo = insertedAt; + insertion = " " + inlinePair + ","; + } else { + insertedAt = close; + spliceTo = insertedAt; + insertion = (existingMembers ? ", " : (hasInlineWhitespace(b, trimmed[0] + 1, close) ? " " : "")) + inlinePair; + } + } + result = Bytes.text(b, 0, insertedAt) + insertion + + Bytes.text(b, spliceTo, b.length); + layoutFrom = insertedAt; + layoutTo = spliceTo; + layoutInserted = insertion.getBytes(java.nio.charset.StandardCharsets.UTF_8).length; + layoutEligible = true; + } else if (node.slot != null && node.slot.kind == EditTree.Slot.BLOCK) { + int closeLine = lineStart(b, node.slot.b1 - 1); + String indent = lineIndent(b, node.slot.b0); + String childIndent = siblingIndent(b, node); + if (childIndent == null) childIndent = indent + " "; + String eol = detectEol(b, node.slot.b1); + String blockPair = standalonePair(key, replacement, childIndent, eol); + int insertAt = closeLine; + String prefix = insertAt > 0 && b[insertAt - 1] != '\n' + && b[insertAt - 1] != '\r' ? eol : ""; + result = Bytes.text(b, 0, insertAt) + prefix + childIndent + blockPair + eol + + Bytes.text(b, insertAt, b.length); + } else if (parentPath.isEmpty() && tree.rootExplicit) { + int at = tree.rootClose; + if (at < bomStart || at >= b.length || b[at] != '}') + throw EditError.unsupported("explicit root Object has no recorded closing brace"); + String childIndent = node.entries.isEmpty() ? " " : siblingIndent(b, node); + if (childIndent == null) childIndent = " "; + String eol = detectEol(b, at); + String blockPair = standalonePair(key, replacement, childIndent, eol); + int insertAt = lineStart(b, at); + if (insertAt < bomStart) insertAt = at; + String prefix = insertAt > bomStart && b[insertAt - 1] != '\n' + && b[insertAt - 1] != '\r' ? eol : ""; + result = Bytes.text(b, 0, insertAt) + prefix + childIndent + blockPair + eol + + Bytes.text(b, insertAt, b.length); + } else { + int at = b.length; + String eol = detectEol(b, b.length); + String blockPair = standalonePair(key, replacement, "", eol); + boolean hasFinalEol = at > 0 && (b[at - 1] == '\n' || b[at - 1] == '\r'); + String addition; + if (at == bomStart && bomStart > 0) { + addition = eol + blockPair; + } else if (at == 0) { + addition = blockPair; + } else if (hasFinalEol) { + addition = blockPair + eol; + } else { + addition = eol + blockPair; + } + result = Bytes.text(b, 0, at) + addition; + } + + byte[] rb = result.getBytes(java.nio.charset.StandardCharsets.UTF_8); + Value reparsed; + try { reparsed = PureParser.parse(rb, bomStart, false); } + catch (SourceError e) { throw EditError.unsupported("patch produced an invalid document: " + e.getMessage()); } + LinkedHashMap expectedMap = new LinkedHashMap<>(object.entries()); + expectedMap.put(key, replacement); + Value expected = replaceAt(original, parentPath, new Value.Obj(expectedMap)); + if (!expected.equals(reparsed)) throw EditError.unsupported("semantic mismatch after insertion"); + if (layoutEligible) { + String adjusted; + try { + adjusted = Layout.adjust(b, result, tree.root, parentPath, replacement, + layoutFrom, layoutTo, layoutInserted); + } catch (EditError layoutFailure) { + return result; + } + if (!adjusted.equals(result)) { + byte[] ab = adjusted.getBytes(java.nio.charset.StandardCharsets.UTF_8); + try { + Value laidOut = PureParser.parse(ab, bomStart, false); + if (expected.equals(laidOut)) result = adjusted; + } catch (SourceError ignored) { + // Preserve the already-verified inline insertion candidate. + } + } + } + return result; + } + + private static boolean isInlineBody(byte[] b, int from, int to) { + int[] body = Bytes.trim(b, from, to); + return body[1] - body[0] >= 2 && b[body[0]] == '{' && b[body[1] - 1] == '}'; + } + + private static String standalonePair(String key, Value value, String indent, String eol) { + String encodedKey = encodeInsertKeySegment(key); + boolean compound = value instanceof Value.Obj || value instanceof Value.Arr; + boolean emptyCompound = value instanceof Value.Obj o && o.entries().isEmpty() + || value instanceof Value.Arr a && a.items().isEmpty(); + if (!compound || emptyCompound) { + PlanCtx pc = new PlanCtx(); + pc.slot = EditTree.Slot.PAIR; + pc.roleItemBlock = false; + pc.existingRaw = false; + pc.rootFirst = false; + pc.indent = indent; + pc.eol = eol; + pc.inlineCompound = false; + pc.blockCompound = true; + Planned planned = planValue(value, pc); + String marker = planned.desiredRaw ? "::" : ":"; + return encodedKey + marker + " " + planned.body; + } + LinkedHashMap one = new LinkedHashMap<>(); + one.put(key, value); + final String rendered; + try { + rendered = PureWriter.dumps(new Value.Obj(one)); + } catch (KtavException e) { + throw EditError.unsupported("replacement is not representable: " + e.getMessage()); + } + String normalized = rendered; + if (normalized.endsWith("\n")) normalized = normalized.substring(0, normalized.length() - 1); + String out = reindentInsert(normalized, indent, eol); + return out; + } + + private static String siblingIndent(byte[] b, EditTree.Node node) { + if (node.kind != EditTree.Node.OBJECT || node.entries.isEmpty()) return null; + EditTree.Node last = null; + for (EditTree.Node child : node.entries.values()) last = child; + if (last == null || last.slot == null) return null; + int pos = last.slot.kind == EditTree.Slot.BLOCK ? last.slot.b0 + : last.slot.kind == EditTree.Slot.PAIR ? last.slot.anchor : last.slot.anchor; + return lineIndent(b, pos); + } + + private static Value replaceAt(Value root, List path, Value value) { + if (path.isEmpty()) return value; + String head = path.get(0); + List rest = path.subList(1, path.size()); + if (root instanceof Value.Obj o) { + LinkedHashMap entries = new LinkedHashMap<>(o.entries()); + Value child = entries.get(head); + if (child == null) throw EditError.notFound(); + entries.put(head, replaceAt(child, rest, value)); + return new Value.Obj(entries); + } + if (root instanceof Value.Arr a) { + int index = parseIndex(head); + if (index >= a.items().size()) throw EditError.notFound(); + List items = new ArrayList<>(a.items()); + items.set(index, replaceAt(items.get(index), rest, value)); + return new Value.Arr(items); + } + throw EditError.notFound(); + } + + private static int lineStart(byte[] b, int pos) { + int i = Math.min(pos, b.length); + while (i > 0 && b[i - 1] != '\n' && b[i - 1] != '\r') i--; + return i; + } + + private static boolean hasInlineWhitespace(byte[] b, int from, int to) { + for (int i = from; i < to; ) { + int cp = b[i] & 0xff; + int len = cp < 0x80 ? 1 : cp < 0xe0 ? 2 : cp < 0xf0 ? 3 : 4; + if (i + len > to) return false; + String unit = new String(b, i, len, java.nio.charset.StandardCharsets.UTF_8); + if (unit.codePointCount(0, unit.length()) != 1 || !isKtavWhitespace(unit.codePointAt(0))) return false; + i += len; + } + return to > from; + } + + private static boolean isKtavWhitespace(int cp) { + return cp == 0x09 || cp == 0x0b || cp == 0x0c || cp == 0x20 + || cp == 0x85 || cp == 0xa0 || cp == 0x1680 + || cp >= 0x2000 && cp <= 0x200a || cp == 0x2028 + || cp == 0x2029 || cp == 0x202f || cp == 0x205f + || cp == 0x3000; + } + + private static boolean hasInlineMember(byte[] b, int from, int to) { + return Bytes.trim(b, from, to)[0] < Bytes.trim(b, from, to)[1]; + } /** * Replace the value addressed by {@code segments} in validated * source {@code b} (whose grammar begins at {@code bomStart}) with @@ -560,6 +828,13 @@ private static void pushInlineValue(Value v, int depth, StringBuilder out) { } } + private static String encodeInsertKeySegment(String key) { + if (key.isEmpty()) throw EditError.unsupported("empty key name is not representable"); + StringBuilder out = new StringBuilder(); + PureWriter.pushEscapedKeySegment(key, false, out); + return out.toString(); + } + /** § 5.9.10 key emission for inline compounds: bare, else quoted+escaped. */ private static String encodeKeySegment(String key) { StringBuilder out = new StringBuilder(); @@ -1025,4 +1300,30 @@ private static int[] scanExponent(String s, int from) { } return scanDecPart(s, i); } + + private static String reindentInsert(String doc, String indent, String eol) { + StringBuilder out = new StringBuilder(doc.length()); + boolean inVerbatim = false; + String[] lines = doc.split("\n", -1); + for (int i = 0; i < lines.length; i++) { + String line = lines[i]; + int leading = 0; + while (leading < line.length() && line.charAt(leading) == ' ') leading++; + String trimmed = line.substring(leading); + boolean closingMarker = inVerbatim && trim(line).equals("))"); + boolean opens = !inVerbatim && trimmed.endsWith("(("); + if (i > 0) out.append(eol); + if (closingMarker) { + out.append(indent).append(line); + inVerbatim = false; + } else if (inVerbatim) { + out.append(line); + } else { + if (i == 0) out.append(line); + else out.append(indent).append(line); + if (opens) inVerbatim = true; + } + } + return out.toString(); + } } diff --git a/lib/src/main/java/lang/ktav/pure/EditTree.java b/lib/src/main/java/lang/ktav/pure/EditTree.java index 1b98d7c..ca694e6 100644 --- a/lib/src/main/java/lang/ktav/pure/EditTree.java +++ b/lib/src/main/java/lang/ktav/pure/EditTree.java @@ -114,6 +114,7 @@ private static final class Frame { private boolean rootConsumed; private Node rootInline; private boolean rootIsExplicit; + private int rootClose = -1; private EditTree(byte[] b) { this.b = b; @@ -139,16 +140,18 @@ static Result build(byte[] b) { lineStart = (b[pos] == '\r' && pos + 1 < n && b[pos + 1] == '\n') ? pos + 2 : pos + 1; } - return new Result(t.finish(), t.rootIsExplicit); + return new Result(t.finish(), t.rootIsExplicit, t.rootClose); } static final class Result { final Node root; final boolean rootExplicit; + final int rootClose; - Result(Node root, boolean rootExplicit) { + Result(Node root, boolean rootExplicit, int rootClose) { this.root = root; this.rootExplicit = rootExplicit; + this.rootClose = rootClose; } } @@ -412,6 +415,7 @@ private void attachScalar(Node node, int lineNum) { private void closeFrame(boolean object, int lineNum, int ts, int te) { if (stack.size() == 1 && rootIsExplicit) { + rootClose = ts; rootConsumed = true; return; } @@ -534,7 +538,7 @@ private Node positionInlineTop(int from, int to) { private Node positionInline(int from, int to, int depth) { boolean isObject = b[from] == '{'; List segments = new ArrayList<>(); - splitTopLevel(from + 1, to - 1, isObject, segments); + splitTopLevelInternal(from + 1, to - 1, isObject, segments); if (isObject) { Node table = new Node(Node.OBJECT, true, null); for (int[] seg : segments) { @@ -594,7 +598,14 @@ private Node inlineChild(int v, int e, int depth) { * final segment. Input already parsed successfully — any surprise is * an internal error. */ - private void splitTopLevel(int from, int to, boolean isObject, + static List splitTopLevel(byte[] bytes, int from, int to, boolean isObject) { + EditTree tree = new EditTree(bytes); + List segments = new ArrayList<>(); + tree.splitTopLevelInternal(from, to, isObject, segments); + return segments; + } + + private void splitTopLevelInternal(int from, int to, boolean isObject, List out) { int i = from; int segAt = from; diff --git a/lib/src/main/java/lang/ktav/pure/Layout.java b/lib/src/main/java/lang/ktav/pure/Layout.java index 09d6b00..a1d6ac3 100644 --- a/lib/src/main/java/lang/ktav/pure/Layout.java +++ b/lib/src/main/java/lang/ktav/pure/Layout.java @@ -80,7 +80,7 @@ private static long[] inlineOwner(byte[] source, EditTree.Node root, && (source[start + 2] & 0xFF) == 0xBF) { start += 3; } - return new long[] { start, t[1] }; + return new long[] { Bytes.skipWs(source, start, t[1]), t[1] }; } for (String segment : path) { if (node.kind == EditTree.Node.OBJECT) { diff --git a/lib/src/main/java/lang/ktav/pure/PureKtav.java b/lib/src/main/java/lang/ktav/pure/PureKtav.java index 3787f46..f1989a9 100644 --- a/lib/src/main/java/lang/ktav/pure/PureKtav.java +++ b/lib/src/main/java/lang/ktav/pure/PureKtav.java @@ -193,6 +193,130 @@ public static String version() { // Lossless source edits (spec 0.9) // ------------------------------------------------------------------ + // ------------------------------------------------------------------ + // Object insertion + // ------------------------------------------------------------------ + + /** Insert a value at a textual dotted path; the final segment must be a new Object key. */ + public static String insertValue(String src, String path, Value value) { + return insertValue(encoded(src), path, value); + } + + /** Byte-level variant; validates and parses source before path/value errors. */ + public static String insertValue(byte[] src, String path, Value value) { + if (src == null) throw new NullPointerException("src"); + if (value == null) throw new NullPointerException("value"); + Validated v = parseSourceFirst(src); + Value replacement = canonicalizeWire(value); + List segments; + try { + segments = EditPath.parse(pathBytes(path)); + } catch (EditError e) { + throw editFailure(envelopeFor(e)); + } + return applyInsert(v, segments, replacement); + } + + /** Insert using pre-decoded literal path segments. */ + public static String insertValueSegments(String src, List segments, Value value) { + return insertValueSegments(encoded(src), segments, value); + } + + /** Byte-level variant of {@link #insertValueSegments(String, List, Value)}. */ + public static String insertValueSegments(byte[] src, List segments, Value value) { + if (src == null) throw new NullPointerException("src"); + if (segments == null) throw new NullPointerException("segments"); + if (value == null) throw new NullPointerException("value"); + Validated v = parseSourceFirst(src); + Value replacement = canonicalizeWire(value); + if (segments.isEmpty()) throw editFailure(ErrorEnvelope.of( + "EditNotFound", null, null, null, null, null, null, null, null, null, + "edit path does not address an Object member")); + return applyInsert(v, segments, replacement); + } + + private static String applyInsert(Validated v, List segments, Value replacement) { + try { + return EditSplice.insert(v.b, v.start, segments, replacement); + } catch (EditError e) { + throw editFailure(envelopeFor(e)); + } catch (SourceError e) { + throw KtavException.fromEnvelope(ErrorEnvelope.of(e.error, e.reason, e.line, + e.lineText, e.spanStart, e.spanEnd, e.path, e.body, e.canonical, + e.specSection, e.getMessage())); + } + } + + // ------------------------------------------------------------------ + // Object removal and key rename + // ------------------------------------------------------------------ + + public static String removeValue(String src, String path) { + return removeValue(encoded(src), path); + } + + public static String removeValue(byte[] src, String path) { + if (src == null) throw new NullPointerException("src"); + Validated v = parseSourceFirst(src); + List segments; + try { segments = EditPath.parse(pathBytes(path)); } + catch (EditError e) { throw editFailure(envelopeFor(e)); } + return applyRemove(v, segments); + } + + public static String removeValueSegments(String src, List segments) { + return removeValueSegments(encoded(src), segments); + } + + public static String removeValueSegments(byte[] src, List segments) { + if (src == null) throw new NullPointerException("src"); + if (segments == null) throw new NullPointerException("segments"); + Validated v = parseSourceFirst(src); + return applyRemove(v, segments); + } + + private static String applyRemove(Validated v, List segments) { + try { return RemoveSplice.apply(v.b, v.start, segments); } + catch (EditError e) { throw editFailure(envelopeFor(e)); } + catch (SourceError e) { throw KtavException.fromEnvelope(ErrorEnvelope.of(e.error, + e.reason, e.line, e.lineText, e.spanStart, e.spanEnd, e.path, + e.body, e.canonical, e.specSection, e.getMessage())); } + } + + public static String renameKey(String src, String path, String newKey) { + return renameKey(encoded(src), path, newKey); + } + + public static String renameKey(byte[] src, String path, String newKey) { + if (src == null) throw new NullPointerException("src"); + if (newKey == null) throw new NullPointerException("newKey"); + Validated v = parseSourceFirst(src); + List segments; + try { segments = EditPath.parse(pathBytes(path)); } + catch (EditError e) { throw editFailure(envelopeFor(e)); } + return applyRename(v, segments, newKey); + } + + public static String renameKeySegments(String src, List segments, String newKey) { + return renameKeySegments(encoded(src), segments, newKey); + } + + public static String renameKeySegments(byte[] src, List segments, String newKey) { + if (src == null) throw new NullPointerException("src"); + if (segments == null) throw new NullPointerException("segments"); + if (newKey == null) throw new NullPointerException("newKey"); + Validated v = parseSourceFirst(src); + return applyRename(v, segments, newKey); + } + + private static String applyRename(Validated v, List segments, String newKey) { + try { return RenameSplice.apply(v.b, v.start, segments, newKey); } + catch (EditError e) { throw editFailure(envelopeFor(e)); } + catch (SourceError e) { throw KtavException.fromEnvelope(ErrorEnvelope.of(e.error, + e.reason, e.line, e.lineText, e.spanStart, e.spanEnd, e.path, + e.body, e.canonical, e.specSection, e.getMessage())); } + } + /** * Replace an existing value addressed by the textual dotted path * ({@code key1.key2.0.key4}; {@code \.} is a literal dot, {@code \\} @@ -403,6 +527,9 @@ private static lang.ktav.internal.ErrorEnvelope envelopeFor(EditError e) { case NOT_FOUND -> ErrorEnvelope.of( "EditNotFound", null, null, null, null, null, null, null, null, null, e.getMessage()); + case ALREADY_EXISTS -> ErrorEnvelope.of( + "EditAlreadyExists", null, null, null, null, null, null, + null, null, null, e.getMessage()); case UNSUPPORTED -> ErrorEnvelope.of( "EditUnsupported", null, null, null, null, null, null, e.reason, null, null, e.getMessage()); diff --git a/lib/src/main/java/lang/ktav/pure/RemoveSplice.java b/lib/src/main/java/lang/ktav/pure/RemoveSplice.java new file mode 100644 index 0000000..41b16ff --- /dev/null +++ b/lib/src/main/java/lang/ktav/pure/RemoveSplice.java @@ -0,0 +1,253 @@ +package lang.ktav.pure; + +import java.nio.charset.StandardCharsets; +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; + +import lang.ktav.Value; + +/** Lossless source splices for removing existing values. */ +final class RemoveSplice { + private RemoveSplice() { } + + static String apply(byte[] source, int bomStart, List segments) { + Value original = PureParser.parse(source, bomStart, false); + if (segments.isEmpty()) throw EditError.notFound(); + EditTree.Result tree = EditTree.build(source); + Parent parent = parent(original, segments); + EditTree.Node parentNode = descend(tree.root, segments.subList(0, segments.size() - 1)); + String leaf = segments.get(segments.size() - 1); + EditTree.Node target; + int index = -1; + if (parent.value instanceof Value.Obj object) { + if (!object.entries().containsKey(leaf)) throw EditError.notFound(); + target = parentNode.entries.get(leaf); + } else if (parent.value instanceof Value.Arr array) { + index = arrayIndex(leaf, array.items().size()); + target = parentNode.items.get(index); + } else throw EditError.notFound(); + if (target == null || target.slot == null) + throw EditError.unsupported("target is a noncontiguous value; no lossless removal range exists"); + int from, to; + boolean inlineParent = target.inline; + if (inlineParent) { + int[] range = inlineRange(source, parentNode, target, tree, segments.size() == 1); + from = range[0]; to = range[1]; + } else { + from = lineStart(source, target.slot.kind == EditTree.Slot.BLOCK + ? target.slot.b0 : target.slot.anchor); + if (from == 0) from = bomStart; + to = target.slot.kind == EditTree.Slot.BLOCK + ? target.slot.b1 : lineEnd(source, target.slot.b1); + if (to < source.length && source[to] == '\r') { + to++; if (to < source.length && source[to] == '\n') to++; + } else if (to < source.length && source[to] == '\n') to++; + if (to == source.length && from < to + && source[to - 1] != '\n' && source[to - 1] != '\r') { + if (from > 0 && source[from - 1] == '\n') { + from--; if (from > 0 && source[from - 1] == '\r') from--; + } else if (from > 0 && source[from - 1] == '\r') from--; + } + } + if (target.kind == EditTree.Node.OBJECT || target.kind == EditTree.Node.ARRAY) { + List ranges = new ArrayList<>(); + collectMultilineScalarRanges(target, ranges); + if (hasCommentLine(source, from, to, ranges)) + throw EditError.unsupported("target contains comment lines; removal cannot preserve them losslessly"); + } + String result = Bytes.text(source, 0, from) + Bytes.text(source, to, source.length); + byte[] bytes = result.getBytes(StandardCharsets.UTF_8); + Value parsed = null; + try { parsed = PureParser.parse(bytes, bomStart, false); } + catch (SourceError ignored) { /* try no-prune materialization below */ } + Value expected = removeAt(original, segments, index); + if (expected.equals(parsed)) return result; + String materialized = materializeEmptyDotted(source, from, to, segments, expected, tree.root, + bomStart); + if (materialized == null) throw EditError.unsupported("semantic mismatch after removal"); + result = materialized; + bytes = result.getBytes(StandardCharsets.UTF_8); + try { parsed = PureParser.parse(bytes, bomStart, false); } + catch (SourceError e) { throw EditError.unsupported("patch produced an invalid document: " + e.getMessage()); } + if (!expected.equals(parsed)) throw EditError.unsupported("semantic mismatch after removal"); + return result; + } + + private static String materializeEmptyDotted(byte[] source, int from, int to, + List path, Value expected, + EditTree.Node root, int bomStart) { + if (path.size() < 2 || to <= from) return null; + Value v = expected; + for (int i = 0; i < path.size() - 1; i++) { + if (v instanceof Value.Obj o) v = o.entries().get(path.get(i)); + else if (v instanceof Value.Arr a) { + int index; + try { index = arrayIndex(path.get(i), a.items().size()); } + catch (EditError e) { return null; } + v = a.items().get(index); + } else return null; + if (v == null) return null; + } + if (!(v instanceof Value.Obj o) || !o.entries().isEmpty()) return null; + int emptyAt = -1; + for (int i = 0; i < path.size() - 1; i++) { + if (isEmptyObjectAt(expected, path, i + 1)) { emptyAt = i; break; } + } + if (emptyAt < 0) return null; + int containerDepth = 0; + EditTree.Node cursor = root; + for (int i = 0; i < path.size() - 1; i++) { + String segment = path.get(i); + if (cursor.kind == EditTree.Node.OBJECT) cursor = cursor.entries.get(segment); + else if (cursor.kind == EditTree.Node.ARRAY) { + int index; + try { index = arrayIndex(segment, cursor.items.size()); } + catch (EditError e) { return null; } + cursor = cursor.items.get(index); + } else break; + if (cursor == null) break; + if (cursor.slot != null) containerDepth = i + 1; + } + if (emptyAt < containerDepth) return null; + int leadLen = from < source.length && source[from] == '\r' + ? (from + 1 < source.length && source[from + 1] == '\n' ? 2 : 1) + : from < source.length && source[from] == '\n' ? 1 : 0; + int lineStartOff = from + leadLen; + int indentEnd = lineStartOff; + while (indentEnd < to && Bytes.wsAt(source, indentEnd, to) > 0) + indentEnd += Bytes.wsAt(source, indentEnd, to); + String indent = Bytes.text(source, lineStartOff, indentEnd); + StringBuilder key = new StringBuilder(); + for (int i = containerDepth; i <= path.size() - 2; i++) { + if (i > containerDepth) key.append('.'); + PureWriter.pushEscapedKeySegment(path.get(i), false, key); + } + String suffix = Bytes.text(source, to, source.length); + String ending = ""; + if (to > from && (source[to - 1] == '\n' || source[to - 1] == '\r')) { + if (source[to - 1] == '\n' && to >= 2 && source[to - 2] == '\r') ending = "\r\n"; + else ending = source[to - 1] == '\n' ? "\n" : "\r"; + } + return Bytes.text(source, 0, from) + Bytes.text(source, from, lineStartOff) + + indent + key + ": {}" + ending + suffix; + } + + private static boolean isEmptyObjectAt(Value root, List path, int depth) { + Value value = root; + for (int i = 0; i < depth; i++) { + String segment = path.get(i); + if (value instanceof Value.Obj object) value = object.entries().get(segment); + else if (value instanceof Value.Arr array) { + try { value = array.items().get(arrayIndex(segment, array.items().size())); } + catch (EditError e) { return false; } + } else return false; + if (value == null) return false; + } + return value instanceof Value.Obj object && object.entries().isEmpty(); + } + + private static int[] inlineRange(byte[] source, EditTree.Node parent, EditTree.Node target, + EditTree.Result tree, boolean root) { + int p0, p1; + if (root) { + int anchorLine = lineStart(source, target.slot.anchor); + int anchorEnd = lineEnd(source, target.slot.anchor); + int[] trimmed = Bytes.trim(source, anchorLine, anchorEnd); + p0 = trimmed[0]; p1 = trimmed[1]; + if (p0 + 2 < p1 && source[p0] == (byte) 0xef + && source[p0 + 1] == (byte) 0xbb && source[p0 + 2] == (byte) 0xbf) p0 += 3; + } else { + if (parent.slot == null) + throw EditError.unsupported("inline parent range unavailable"); + p0 = parent.slot.b0; p1 = parent.slot.b1; + } + int anchor = target.slot.anchor; + int open = p0; + while (open < p1 && source[open] != '{' && source[open] != '[') open++; + if (open == p1) throw EditError.unsupported("inline parent range unavailable"); + int close = p1 - 1; + List spans = EditTree.splitTopLevel(source, open + 1, close, source[open] == '{'); + for (int[] span : spans) { + int[] trimmed = Bytes.trim(source, span[0], span[1]); + span[0] = trimmed[0]; span[1] = trimmed[1]; + } + int pos = -1; for (int i=0;i spans, int a, int z) { + int[] trimmed = Bytes.trim(b, a, z); + if (trimmed[0] < trimmed[1]) spans.add(new int[]{trimmed[0], trimmed[1]}); + } + private static void collectMultilineScalarRanges(EditTree.Node node, List out) { + if (node.kind == EditTree.Node.SCALAR && node.slot != null + && node.slot.kind == EditTree.Slot.BLOCK) { + out.add(new int[]{node.slot.b0, node.slot.b1}); + return; + } + if (node.kind == EditTree.Node.OBJECT) { + for (EditTree.Node child : node.entries.values()) collectMultilineScalarRanges(child, out); + } else if (node.kind == EditTree.Node.ARRAY) { + for (EditTree.Node child : node.items) collectMultilineScalarRanges(child, out); + } + } + + private static boolean hasCommentLine(byte[] b, int from, int to, List skip) { + skip.sort((x, y) -> Integer.compare(x[0], y[0])); + int skipI = 0; + for (int i = from; i < to;) { + int j = i; + while (j < to && b[j] != '\n' && b[j] != '\r') j++; + int[] t = Bytes.trim(b, i, j); + while (skipI < skip.size() && skip.get(skipI)[1] <= t[0]) skipI++; + boolean inData = skipI < skip.size() && skip.get(skipI)[0] <= t[0] + && t[0] < skip.get(skipI)[1]; + if (!inData && t[1] - t[0] >= 2 && b[t[0]] == '#' && b[t[0] + 1] == '#') return true; + i = j; + while (i < to && (b[i] == '\n' || b[i] == '\r')) i++; + } + return false; + } + + private static final class Parent { final Value value; Parent(Value value) { this.value = value; } } + private static Parent parent(Value root, List path) { + Value v = root; + for (int i = 0; i + 1 < path.size(); i++) { + String s = path.get(i); + if (v instanceof Value.Obj o) v = o.entries().get(s); + else if (v instanceof Value.Arr a) { int n = arrayIndex(s, a.items().size()); v = a.items().get(n); } + else throw EditError.notFound(); + if (v == null) throw EditError.notFound(); + } + return new Parent(v); + } + private static int arrayIndex(String s, int size) { + if (s.isEmpty() || !s.chars().allMatch(c -> c >= '0' && c <= '9')) throw EditError.notFound(); + try { int i = Integer.parseInt(s); if (i < 0 || i >= size) throw EditError.notFound(); return i; } + catch (NumberFormatException e) { throw EditError.notFound(); } + } + private static EditTree.Node descend(EditTree.Node n, List path) { + for (String s : path) { + if (n.kind == EditTree.Node.OBJECT) n = n.entries.get(s); + else if (n.kind == EditTree.Node.ARRAY) { int i = arrayIndex(s, n.items.size()); n = n.items.get(i); } + else throw EditError.notFound(); + if (n == null) throw EditError.notFound(); + } + return n; + } + private static Value removeAt(Value root, List path, int arrayIndex) { + if (path.size() == 1) { + if (root instanceof Value.Obj o) { LinkedHashMap m = new LinkedHashMap<>(o.entries()); m.remove(path.get(0)); return new Value.Obj(m); } + if (root instanceof Value.Arr a) { int i = arrayIndex(path.get(0), a.items().size()); List l = new ArrayList<>(a.items()); l.remove(i); return new Value.Arr(l); } + throw EditError.notFound(); + } + String h = path.get(0); List rest = path.subList(1, path.size()); + if (root instanceof Value.Obj o) { LinkedHashMap m = new LinkedHashMap<>(o.entries()); Value c = m.get(h); if (c == null) throw EditError.notFound(); m.put(h, removeAt(c, rest, -1)); return new Value.Obj(m); } + if (root instanceof Value.Arr a) { int i = arrayIndex(h, a.items().size()); List l = new ArrayList<>(a.items()); l.set(i, removeAt(l.get(i), rest, -1)); return new Value.Arr(l); } + throw EditError.notFound(); + } + private static int lineStart(byte[] b, int p) { while (p > 0 && b[p-1] != '\n' && b[p-1] != '\r') p--; return p; } + private static int lineEnd(byte[] b, int p) { while (p < b.length && b[p] != '\n' && b[p] != '\r') p++; return p; } +} diff --git a/lib/src/main/java/lang/ktav/pure/RenameSplice.java b/lib/src/main/java/lang/ktav/pure/RenameSplice.java new file mode 100644 index 0000000..b76299a --- /dev/null +++ b/lib/src/main/java/lang/ktav/pure/RenameSplice.java @@ -0,0 +1,106 @@ +package lang.ktav.pure; + +import java.nio.charset.StandardCharsets; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +import lang.ktav.Value; + +/** Lossless source splice for renaming one Object member. */ +final class RenameSplice { + private RenameSplice() { } + + static String apply(byte[] source, int bomStart, List segments, String newKey) { + Value original = PureParser.parse(source, bomStart, false); + if (segments.isEmpty()) throw EditError.notFound(); + if (newKey.isEmpty()) throw EditError.unsupported("empty key name is not representable"); + String oldKey = segments.get(segments.size() - 1); + Value parent = original; + EditTree.Result tree = EditTree.build(source); + EditTree.Node node = tree.root; + for (int i = 0; i < segments.size() - 1; i++) { + String s = segments.get(i); + if (parent instanceof Value.Obj o) parent = o.entries().get(s); + else if (parent instanceof Value.Arr a) parent = a.items().get(index(s, a.items().size())); + else throw EditError.notFound(); + if (parent == null) throw EditError.notFound(); + node = node.kind == EditTree.Node.OBJECT ? node.entries.get(s) : node.kind == EditTree.Node.ARRAY ? node.items.get(index(s, node.items.size())) : null; + if (node == null) throw EditError.notFound(); + } + if (parent instanceof Value.Arr) throw EditError.unsupported("rename of an Array element is not supported; only Object keys can be renamed"); + if (!(parent instanceof Value.Obj object) || !object.entries().containsKey(oldKey)) throw EditError.notFound(); + if (oldKey.equals(newKey)) return Bytes.text(source, 0, source.length); + if (object.entries().containsKey(newKey)) throw EditError.alreadyExists(); + EditTree.Node target = node.entries.get(oldKey); + if (target == null) throw EditError.notFound(); + if (target.slot == null) throw EditError.unsupported("target is a noncontiguous value (dotted-key/reopen intermediate); no lossless rename range exists"); + if (target.slot.kind == EditTree.Slot.ITEM || target.slot.kind == EditTree.Slot.BLOCK && target.slot.anchor < 0) + throw EditError.unsupported("rename of an Array element is not supported; only Object keys can be renamed"); + int colon = target.slot.anchor; + int[] keyRange = pairKeyRange(source, colon); + int keyStart = keyRange[0], keyEnd = keyRange[1]; + if (keyStart >= keyEnd) throw EditError.unsupported("internal: empty key range"); + List rawSegments = Keys.splitPath(source, keyStart, keyEnd); + int[] lastSegment = rawSegments.get(rawSegments.size() - 1); + int segFrom = lastSegment[0], segTo = lastSegment[1]; + int[] trimmed = Bytes.trim(source, segFrom, segTo); + segFrom = trimmed[0]; segTo = trimmed[1]; + boolean rootFirst = segments.size() == 1 && node.entries.keySet().iterator().next().equals(oldKey); + StringBuilder encoded = new StringBuilder(); + PureWriter.pushEscapedKeySegment(newKey, rootFirst, encoded); + String result = Bytes.text(source, 0, segFrom) + encoded + Bytes.text(source, segTo, source.length); + Value reparsed; + try { reparsed = PureParser.parse(result.getBytes(StandardCharsets.UTF_8), bomStart, false); } + catch (SourceError e) { throw EditError.unsupported("patch produced an invalid document: " + e.getMessage()); } + LinkedHashMap renamed = new LinkedHashMap<>(); + for (Map.Entry entry : object.entries().entrySet()) renamed.put(entry.getKey().equals(oldKey) ? newKey : entry.getKey(), entry.getValue()); + Value expected = replaceParent(original, segments.subList(0, segments.size() - 1), new Value.Obj(renamed)); + if (!expected.equals(reparsed)) throw EditError.unsupported("semantic mismatch after rename"); + return result; + } + private static Value replaceParent(Value root, List path, Value replacement) { + if (path.isEmpty()) return replacement; + String h = path.get(0); List rest = path.subList(1, path.size()); + if (root instanceof Value.Obj o) { LinkedHashMap m = new LinkedHashMap<>(o.entries()); Value c=m.get(h); if(c==null) throw EditError.notFound(); m.put(h, replaceParent(c,rest,replacement)); return new Value.Obj(m); } + if (root instanceof Value.Arr a) { int i=index(h,a.items().size()); java.util.ArrayList l=new java.util.ArrayList<>(a.items()); l.set(i,replaceParent(l.get(i),rest,replacement)); return new Value.Arr(l); } + throw EditError.notFound(); + } + private static int index(String s, int size) { if(s.isEmpty() || !s.chars().allMatch(c -> c>='0'&&c<='9')) throw EditError.notFound(); try { int i=Integer.parseInt(s); if(i>=size) throw EditError.notFound(); return i; } catch(NumberFormatException e){ throw EditError.notFound(); } } + private static int[] pairKeyRange(byte[] b, int colon) { + int start = lineStart(b, colon); + if (start == 0 && b.length >= 3 && (b[0] & 0xFF) == 0xEF + && (b[1] & 0xFF) == 0xBB && (b[2] & 0xFF) == 0xBF) start = 3; + int end = Bytes.trimEnd(b, start, colon); + int boundary = start; + int i = start; + boolean segmentStart = true; + while (i < end) { + if (segmentStart) { + i = Bytes.skipWs(b, i, end); + if (i < end && (b[i] == '"' || b[i] == '\'' || b[i] == '`')) { + byte quote = b[i++]; + while (i < end) { + if (b[i] == '\\') { i = Math.min(end, i + 2); continue; } + if (b[i++] == quote) break; + } + segmentStart = false; + continue; + } + segmentStart = false; + } + byte c = b[i]; + if (c == '\\') { i = Math.min(end, i + 2); continue; } + if (c == '.' || c == ',' || c == '{' || c == '[') { + boundary = i + 1; + segmentStart = true; + } + i++; + } + return Bytes.trim(b, boundary, end); + } + private static int lineStart(byte[] b, int p) { + while (p > 0 && b[p - 1] != '\n' && b[p - 1] != '\r') p--; + return p; + } +} diff --git a/lib/src/test/java/lang/ktav/PureInsertValueTest.java b/lib/src/test/java/lang/ktav/PureInsertValueTest.java new file mode 100644 index 0000000..6de3fb5 --- /dev/null +++ b/lib/src/test/java/lang/ktav/PureInsertValueTest.java @@ -0,0 +1,426 @@ +package lang.ktav; + +import org.junit.jupiter.api.Test; + +import java.math.BigInteger; +import java.nio.charset.StandardCharsets; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; + +/** Pure source insertion regressions with independent semantic and byte-exact oracles. */ +final class PureInsertValueTest { + private static Value.Int i(String n) { return new Value.Int(n); } + private static Value.Str s(String v) { return new Value.Str(v); } + private static Value.Obj o(Object... pairs) { + java.util.LinkedHashMap m = new java.util.LinkedHashMap<>(); + for (int n = 0; n < pairs.length; n += 2) m.put((String) pairs[n], (Value) pairs[n + 1]); + return new Value.Obj(m); + } + private static void exactAndTree(String output, String expectedBytes, Value expectedTree) { + assertEquals(expectedBytes, output); + assertEquals(expectedTree, lang.ktav.pure.PureKtav.loads(output)); + } + + @Test void rootInlineBlockAndTrailingComma() { + exactAndTree(lang.ktav.pure.PureKtav.insertValue("a: 1\n", "b", i("2")), "a: 1\nb: 2\n", o("a", i("1"), "b", i("2"))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue("cfg: {x: 1,}\n", "cfg.y", i("2")), "cfg: {x: 1, y: 2,}\n", o("cfg", o("x", i("1"), "y", i("2")))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue("plain: {x: 1}\n", "plain.y", i("2")), "plain: {x: 1, y: 2}\n", o("plain", o("x", i("1"), "y", i("2")))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue("cfg: {\n x: 1\n}\n", "cfg.y", i("2")), "cfg: {\n x: 1\n y: 2\n}\n", o("cfg", o("x", i("1"), "y", i("2")))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue("items: [1, 2,]\n", "added", new Value.Bool(true)), "items: [1, 2,]\nadded: true\n", o("items", new Value.Arr(List.of(i("1"), i("2"))), "added", new Value.Bool(true))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue("items: [{x: 1}]\n", "items.0.y", i("2")), "items: [{x: 1, y: 2}]\n", o("items", new Value.Arr(List.of(o("x", i("1"), "y", i("2")))))); + } + + @Test void escapedDelimitersAndSegments() { + exactAndTree(lang.ktav.pure.PureKtav.insertValue("a: 1\n", "a\\.b", i("3")), "a: 1\n\"a.b\": 3\n", o("a", i("1"), "a.b", i("3"))); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments("a: 1\n", List.of("a.b"), i("3")), "a: 1\n\"a.b\": 3\n", o("a", i("1"), "a.b", i("3"))); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments("parent: {}\na: 1\n", List.of("parent", "c,d"), s("v")), "parent: {\"c,d\": v}\na: 1\n", o("parent", o("c,d", s("v")), "a", i("1"))); + } + + @Test void stringAndByteSourcesAndI64() { + String source = "n: 9223372036854775807\n"; + Value expected = o("n", i("9223372036854775807"), "huge", s("9223372036854775808")); + String bytes = source + "huge:: 9223372036854775808\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "huge", s("9223372036854775808")), bytes, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("huge"), s("9223372036854775808")), bytes, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source.getBytes(StandardCharsets.UTF_8), "huge", s("9223372036854775808")), bytes, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source.getBytes(StandardCharsets.UTF_8), List.of("huge"), s("9223372036854775808")), bytes, expected); + assertEquals(new BigInteger("9223372036854775807"), ((Value.Int) ((Value.Obj) lang.ktav.pure.PureKtav.loads(source)).entries().get("n")).toBigInteger()); + } + + @Test void insertionIntoWhitespaceEmptyInlineObjects() { + String source = "parent: { \u2003 }\n"; + byte[] bytes = source.getBytes(StandardCharsets.UTF_8); + Value expected = o("parent", o("child", i("2"))); + String output = "parent: {child: 2}\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.child", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("parent", "child"), i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "parent.child", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("parent", "child"), i("2")), output, expected); + Value strTree = o("parent", o("child", s("v"))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.child", s("v")), "parent: {child: v}\n", strTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("parent", "child"), s("v")), "parent: {child: v}\n", strTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "parent.child", s("v")), "parent: {child: v}\n", strTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("parent", "child"), s("v")), "parent: {child: v}\n", strTree); + } + + @Test void insertionIntoWhitespaceEmptyArrayItemObject() { + String source = "items: [\n { \u2003 }\n]\n"; + byte[] bytes = source.getBytes(StandardCharsets.UTF_8); + Value expected = o("items", new Value.Arr(List.of(o("child", i("2"))))); + String output = "items: [\n {child: 2}\n]\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "items.0.child", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("items", "0", "child"), i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "items.0.child", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("items", "0", "child"), i("2")), output, expected); + } + + @Test void nonemptyStandalonePairAndBlockArrayItemFourOverloads() { + String source = "{a: 1}\n", output = "{a: 1, b: 2}\n"; + Value expected = o("a", i("1"), "b", i("2")); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "b", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("b"), i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source.getBytes(StandardCharsets.UTF_8), "b", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source.getBytes(StandardCharsets.UTF_8), List.of("b"), i("2")), output, expected); + + String item = "items: [\n {x: 1}\n]\n", itemOut = "items: [\n {x: 1, y: two}\n]\n"; + byte[] itemBytes = item.getBytes(StandardCharsets.UTF_8); + Value itemTree = o("items", new Value.Arr(List.of(o("x", i("1"), "y", s("two"))))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(item, "items.0.y", s("two")), itemOut, itemTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(item, List.of("items", "0", "y"), s("two")), itemOut, itemTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(itemBytes, "items.0.y", s("two")), itemOut, itemTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(itemBytes, List.of("items", "0", "y"), s("two")), itemOut, itemTree); + } + + @Test void nestedBlockItemLongAndMultilineFourOverloads() { + String source = "items: [\n {x: 1}\n]\n"; + byte[] bytes = source.getBytes(StandardCharsets.UTF_8); + String longValue = "x".repeat(120); + Value longTree = o("items", new Value.Arr(List.of(o("x", i("1"), "y", s(longValue))))); + String longOutput = "items: [\n {\n x: 1\n y: " + longValue + "\n }\n]\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "items.0.y", s(longValue)), longOutput, longTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("items", "0", "y"), s(longValue)), longOutput, longTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "items.0.y", s(longValue)), longOutput, longTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("items", "0", "y"), s(longValue)), longOutput, longTree); + String multiline = "first\nsecond"; + Value multilineTree = o("items", new Value.Arr(List.of(o("x", i("1"), "y", s(multiline))))); + String multilineOutput = "items: [\n {\n x: 1\n y: ((\nfirst\nsecond\n ))\n }\n]\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "items.0.y", s(multiline)), multilineOutput, multilineTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("items", "0", "y"), s(multiline)), multilineOutput, multilineTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "items.0.y", s(multiline)), multilineOutput, multilineTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("items", "0", "y"), s(multiline)), multilineOutput, multilineTree); + } + + @Test void nestedInlinePairOrdinaryLongAndMultiline() { + String source = "parent: {x: one}\n"; + String inline = "parent: {x: one, y: two}\n"; + Value inlineTree = o("parent", o("x", s("one"), "y", s("two"))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.y", s("two")), inline, inlineTree); + String longValue = "x".repeat(120); + String longOutput = "parent: {\n x: one\n y: " + longValue + "\n}\n"; + Value longTree = o("parent", o("x", s("one"), "y", s(longValue))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.y", s(longValue)), longOutput, longTree); + String multiline = "first\nsecond"; + String multilineOutput = "parent: {\n x: one\n y: ((\nfirst\nsecond\n ))\n}\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.y", s(multiline)), multilineOutput, + o("parent", o("x", s("one"), "y", s(multiline)))); + } + + @Test void rootFormattingBomAndMixedEol() { + exactAndTree(lang.ktav.pure.PureKtav.insertValue("a: 1\r\nb: 2\n", "c", i("3")), "a: 1\r\nb: 2\nc: 3\n", o("a", i("1"), "b", i("2"), "c", i("3"))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue("\uFEFF", "k", i("1")), "\uFEFF\nk: 1", o("k", i("1"))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue("\uFEFF\r\n", "k", i("1")), "\uFEFF\r\nk: 1\r\n", o("k", i("1"))); + String mixed = "parent: {\r\n x: 1\n}\r\ntail: keep\n"; + String mixedOutput = "parent: {\r\n x: 1\n y: 2\r\n}\r\ntail: keep\n"; + Value mixedTree = o("parent", o("x", i("1"), "y", i("2")), "tail", s("keep")); + byte[] mixedBytes = mixed.getBytes(StandardCharsets.UTF_8); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(mixed, "parent.y", i("2")), mixedOutput, mixedTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(mixed, List.of("parent", "y"), i("2")), mixedOutput, mixedTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(mixedBytes, "parent.y", i("2")), mixedOutput, mixedTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(mixedBytes, List.of("parent", "y"), i("2")), mixedOutput, mixedTree); + String crlf = "parent: {\r\n x: 1\r\n}\r\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(crlf, "parent.y", i("2")), "parent: {\r\n x: 1\r\n y: 2\r\n}\r\n", o("parent", o("x", i("1"), "y", i("2")))); + } + + @Test void nestedVerbatimClosingMarkerFourOverloadsAndCrFallback() { + String source = "parent: {x: 1}\n"; + byte[] bytes = source.getBytes(StandardCharsets.UTF_8); + String marker = "first\nlast"; + String output = "parent: {\n x: 1\n marker: ((\nfirst\nlast\n ))\n}\n"; + Value tree = o("parent", o("x", i("1"), "marker", s(marker))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.marker", s(marker)), output, tree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("parent", "marker"), s(marker)), output, tree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "parent.marker", s(marker)), output, tree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("parent", "marker"), s(marker)), output, tree); + String crlfSource = "parent: {\r\n x: 1\r\n}\r\n"; + byte[] crlfBytes = crlfSource.getBytes(StandardCharsets.UTF_8); + Value crlfTree = o("parent", o("x", i("1"), "y", o("z", i("2")))); + String crlfOutput = "parent: {\r\n x: 1\r\n y: {\r\n z: 2\r\n }\r\n}\r\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(crlfSource, "parent.y", o("z", i("2"))), crlfOutput, crlfTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(crlfSource, List.of("parent", "y"), o("z", i("2"))), crlfOutput, crlfTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(crlfBytes, "parent.y", o("z", i("2"))), crlfOutput, crlfTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(crlfBytes, List.of("parent", "y"), o("z", i("2"))), crlfOutput, crlfTree); + } + + @Test void restoredEscapedCommaBackslashCases() { + exactAndTree(lang.ktav.pure.PureKtav.insertValue("parent: {x: p\\,}\n", "parent.q", s("v")), + "parent: {x: p\\,, q: v}\n", o("parent", o("x", s("p,"), "q", s("v")))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue("parent: {}\n", "parent.a\\\\b", s("v")), + "parent: {a\\\\b: v}\n", o("parent", o("a\\b", s("v")))); + } + + @Test void nestedObjectInsertionOverloads() { + String source = "parent: {x: 1}\n"; + byte[] bytes = source.getBytes(StandardCharsets.UTF_8); + Value value = o("z", i("2")); + Value tree = o("parent", o("x", i("1"), "y", value)); + String output = "parent: {x: 1, y: {z: 2}}\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.y", value), output, tree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("parent", "y"), value), output, tree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "parent.y", value), output, tree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("parent", "y"), value), output, tree); + } + + + @Test void standaloneBlockLfEmptyContainersCrlfAndRootEofPolicyFourOverloads() { + String source = "base: 1\n"; + byte[] bytes = source.getBytes(StandardCharsets.UTF_8); + java.util.function.BiConsumer rootCase = (value, output) -> { + Value expected = o("base", i("1"), "k", value); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "k", value), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("k"), value), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "k", value), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("k"), value), output, expected); + }; + rootCase.accept(s("one\ntwo"), "base: 1\nk: ((\none\ntwo\n))\n"); + rootCase.accept(o(), "base: 1\nk: {\n}\n"); + rootCase.accept(new Value.Arr(List.of()), "base: 1\nk: [\n]\n"); + + String nested = "parent: {\r\n x: 1\r\n}\r\n"; + byte[] nestedBytes = nested.getBytes(StandardCharsets.UTF_8); + java.util.function.BiConsumer nestedCase = (value, body) -> { + Value expected = o("parent", o("x", i("1"), "y", value)); + String output = "parent: {\r\n x: 1\r\n y: " + body + "\r\n}\r\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(nested, "parent.y", value), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(nested, List.of("parent", "y"), value), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(nestedBytes, "parent.y", value), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(nestedBytes, List.of("parent", "y"), value), output, expected); + }; + nestedCase.accept(s("one\ntwo"), "((\r\none\r\ntwo\r\n ))"); + nestedCase.accept(o(), "{\r\n }" ); + nestedCase.accept(new Value.Arr(List.of()), "[\r\n ]"); + + String noFinalEol = "base: 1"; + byte[] noFinalEolBytes = noFinalEol.getBytes(StandardCharsets.UTF_8); + String noFinalEolOutput = "base: 1\nk: ((\none\ntwo\n))"; + Value noFinalEolTree = o("base", i("1"), "k", s("one\ntwo")); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(noFinalEol, "k", s("one\ntwo")), noFinalEolOutput, noFinalEolTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(noFinalEol, List.of("k"), s("one\ntwo")), noFinalEolOutput, noFinalEolTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(noFinalEolBytes, "k", s("one\ntwo")), noFinalEolOutput, noFinalEolTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(noFinalEolBytes, List.of("k"), s("one\ntwo")), noFinalEolOutput, noFinalEolTree); + + KtavException cr1 = assertThrows(KtavException.class, () -> lang.ktav.pure.PureKtav.insertValue(source, "k", s("x\ry"))); + KtavException cr2 = assertThrows(KtavException.class, () -> lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("k"), s("x\ry"))); + KtavException cr3 = assertThrows(KtavException.class, () -> lang.ktav.pure.PureKtav.insertValue(bytes, "k", s("x\ry"))); + KtavException cr4 = assertThrows(KtavException.class, () -> lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("k"), s("x\ry"))); + assertEquals("EditUnsupported", cr1.getError()); + assertEquals("EditUnsupported", cr2.getError()); + assertEquals("EditUnsupported", cr3.getError()); + assertEquals("EditUnsupported", cr4.getError()); + } + @Test void malformedUtf8PrecedesInvalidPathAndStandaloneCrIsUnsupported() { + byte[] malformed = {'a', ':', ' ', (byte) 0xff}; + KtavException invalidUtf8 = assertThrows(KtavException.class, + () -> lang.ktav.pure.PureKtav.insertValue(malformed, "\\q", i("1"))); + assertEquals("InvalidUtf8", invalidUtf8.getError()); + KtavException cr = assertThrows(KtavException.class, + () -> lang.ktav.pure.PureKtav.insertValue("a: 1\n", "cr", s("x\ry"))); + assertEquals("EditUnsupported", cr.getError()); + } + + @Test void stringsLoopRootEmptyNonemptyAndBlock() { + String[] values = {"123", "true", "null", "a,b", "a\\b", "line\nfeed"}; + for (String value : values) { + String root = lang.ktav.pure.PureKtav.insertValue("", "value", s(value)); + assertEquals(o("value", s(value)), lang.ktav.pure.PureKtav.loads(root)); + + String empty = lang.ktav.pure.PureKtav.insertValue("parent: {}\n", "parent.child", s(value)); + assertEquals(o("parent", o("child", s(value))), lang.ktav.pure.PureKtav.loads(empty)); + + String nonempty = lang.ktav.pure.PureKtav.insertValue("parent: {x: 0}\n", "parent.y", s(value)); + assertEquals(o("parent", o("x", i("0"), "y", s(value))), lang.ktav.pure.PureKtav.loads(nonempty)); + + String block = lang.ktav.pure.PureKtav.insertValue("parent: {\n x: 0\n}\n", "parent.y", s(value)); + assertEquals(o("parent", o("x", i("0"), "y", s(value))), lang.ktav.pure.PureKtav.loads(block)); + } + } + + @Test void pairAllValueFormsFourOverloads() { + String source = "parent: {x: one}\n"; + byte[] bytes = source.getBytes(StandardCharsets.UTF_8); + String ordinary = "parent: {x: one, y: two}\n"; + Value ordinaryTree = o("parent", o("x", s("one"), "y", s("two"))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.y", s("two")), ordinary, ordinaryTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("parent", "y"), s("two")), ordinary, ordinaryTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "parent.y", s("two")), ordinary, ordinaryTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("parent", "y"), s("two")), ordinary, ordinaryTree); + + String longValue = "x".repeat(120); + String longOutput = "parent: {\n x: one\n y: " + longValue + "\n}\n"; + Value longTree = o("parent", o("x", s("one"), "y", s(longValue))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.y", s(longValue)), longOutput, longTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("parent", "y"), s(longValue)), longOutput, longTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "parent.y", s(longValue)), longOutput, longTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("parent", "y"), s(longValue)), longOutput, longTree); + + String multiline = "first\nsecond"; + String multilineOutput = "parent: {\n x: one\n y: ((\nfirst\nsecond\n ))\n}\n"; + Value multilineTree = o("parent", o("x", s("one"), "y", s(multiline))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.y", s(multiline)), multilineOutput, multilineTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("parent", "y"), s(multiline)), multilineOutput, multilineTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "parent.y", s(multiline)), multilineOutput, multilineTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("parent", "y"), s(multiline)), multilineOutput, multilineTree); + + String bom = "\uFEFF"; + String bomOut = "\uFEFF\nk: 1"; + Value bomTree = o("k", i("1")); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bom, "k", i("1")), bomOut, bomTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bom, List.of("k"), i("1")), bomOut, bomTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bom.getBytes(StandardCharsets.UTF_8), "k", i("1")), bomOut, bomTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bom.getBytes(StandardCharsets.UTF_8), List.of("k"), i("1")), bomOut, bomTree); + + String cr = "first\ry"; + String crOut = "parent: {x: one, y: first\\ry}\n"; + Value crTree = o("parent", o("x", s("one"), "y", s(cr))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.y", s(cr)), crOut, crTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("parent", "y"), s(cr)), crOut, crTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "parent.y", s(cr)), crOut, crTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("parent", "y"), s(cr)), crOut, crTree); + + String markerOut = "parent: {x: one, y: first\\n))\\nlast}\n"; + Value markerTree = o("parent", o("x", s("one"), "y", s("first\n))\nlast"))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.y", s("first\n))\nlast")), markerOut, markerTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("parent", "y"), s("first\n))\nlast")), markerOut, markerTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "parent.y", s("first\n))\nlast")), markerOut, markerTree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("parent", "y"), s("first\n))\nlast")), markerOut, markerTree); + } + + @Test void leadingCommentsAndLiteralRootStringsRemainCovered() { + exactAndTree(lang.ktav.pure.PureKtav.insertValue("## note\n{x: 1}\n", "y", i("2")), + "## note\n{x: 1, y: 2}\n", o("x", i("1"), "y", i("2"))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue("", "k", s("x\\,y")), + "k: x\\,y", o("k", s("x\\,y"))); + exactAndTree(lang.ktav.pure.PureKtav.insertValue("", "k", s("a,b")), + "k: a,b", o("k", s("a,b"))); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments("base: 0\n", List.of("a,b"), i("1")), + "base: 0\n\"a,b\": 1\n", o("base", i("0"), "a,b", i("1"))); + } + + @Test void blockInsertionReindentsVerbatimCloserWithoutChangingData() { + String source = "parent: {\r\n keep: 1\r\n}\r\n"; + Value value = o("value", s("first\n)\nlast")); + String expected = "parent: {\r\n keep: 1\r\n added: {\r\n value: ((\r\nfirst\r\n)\r\nlast\r\n ))\r\n }\r\n}\r\n"; + Value tree = o("parent", o("keep", i("1"), "added", value)); + byte[] bytes = source.getBytes(StandardCharsets.UTF_8); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.added", value), expected, tree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("parent", "added"), value), expected, tree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "parent.added", value), expected, tree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("parent", "added"), value), expected, tree); + } + + @Test void inlineRootLayoutWithBomAndSpaces() { + String source = " {x: 1}\r\n"; + String expected = " {\r\n x: 1\r\n y: ((\r\nfirst\r\nsecond\r\n ))\r\n}\r\n"; + Value value = s("first\nsecond"); + Value tree = o("x", i("1"), "y", value); + byte[] bytes = source.getBytes(StandardCharsets.UTF_8); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "y", value), expected, tree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("y"), value), expected, tree); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "y", value), expected, tree); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("y"), value), expected, tree); + } + + @Test void insertionErrorsAreStable() { + KtavException emptyFinal = assertThrows(KtavException.class, + () -> lang.ktav.pure.PureKtav.insertValueSegments("a: 1\n", List.of(""), i("2"))); + assertEquals("EditUnsupported", emptyFinal.getError()); + KtavException missingBeforeEmpty = assertThrows(KtavException.class, + () -> lang.ktav.pure.PureKtav.insertValueSegments("a: 1\n", List.of("missing", ""), i("2"))); + assertEquals("EditNotFound", missingBeforeEmpty.getError()); + KtavException noncontiguous = assertThrows(KtavException.class, () -> lang.ktav.pure.PureKtav.insertValue("a.x: 1\na.y: 2\n", "a.z", i("3"))); + assertEquals("EditUnsupported", noncontiguous.getError()); + KtavException arrayParent = assertThrows(KtavException.class, () -> lang.ktav.pure.PureKtav.insertValue("items: [1, 2]\n", "items.child", i("3"))); + assertEquals("EditUnsupported", arrayParent.getError()); + KtavException missingParent = assertThrows(KtavException.class, () -> lang.ktav.pure.PureKtav.insertValueSegments("a: 1\n", List.of("missing", "child"), i("2"))); + assertEquals("EditNotFound", missingParent.getError()); + KtavException badPath = assertThrows(KtavException.class, () -> lang.ktav.pure.PureKtav.insertValue("a: 1\n", "a..b", i("2"))); + assertEquals("EditInvalidPath", badPath.getError()); + assertEquals("2", badPath.getBody()); + KtavException exists = assertThrows(KtavException.class, () -> lang.ktav.pure.PureKtav.insertValueSegments("a: 1\n", List.of("a"), i("2"))); + assertEquals("EditAlreadyExists", exists.getError()); + } + + @Test void standaloneAndInlineEscapedKeysAllFourOverloads() { + String source = "base: 1\n"; byte[] bytes = source.getBytes(StandardCharsets.UTF_8); + Value expected = o("base", i("1"), "a b", i("2")); + String output = "base: 1\na b: 2\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "a b", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("a b"), i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "a b", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("a b"), i("2")), output, expected); + + Value edgeExpected = o("base", i("1"), "k", s(" value ")); + String edgeOutput = "base: 1\nk: ((\n value \n))\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "k", s(" value ")), edgeOutput, edgeExpected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("k"), s(" value ")), edgeOutput, edgeExpected); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "k", s(" value ")), edgeOutput, edgeExpected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("k"), s(" value ")), edgeOutput, edgeExpected); + + source = "parent: {x: 1}\n"; bytes = source.getBytes(StandardCharsets.UTF_8); + expected = o("parent", o("x", i("1"), "a b", i("2"))); + output = "parent: {x: 1, a b: 2}\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.a b", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("parent", "a b"), i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "parent.a b", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("parent", "a b"), i("2")), output, expected); + + source = "base: 1\n"; bytes = source.getBytes(StandardCharsets.UTF_8); + expected = o("base", i("1"), "a\\b", i("2")); + output = "base: 1\na\\\\b: 2\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "a\\\\b", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("a\\b"), i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "a\\\\b", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("a\\b"), i("2")), output, expected); + + source = "parent: {x: 1}\n"; bytes = source.getBytes(StandardCharsets.UTF_8); + expected = o("parent", o("x", i("1"), "a\\b", i("2"))); + output = "parent: {x: 1, a\\\\b: 2}\n"; + exactAndTree(lang.ktav.pure.PureKtav.insertValue(source, "parent.a\\\\b", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(source, List.of("parent", "a\\b"), i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValue(bytes, "parent.a\\\\b", i("2")), output, expected); + exactAndTree(lang.ktav.pure.PureKtav.insertValueSegments(bytes, List.of("parent", "a\\b"), i("2")), output, expected); + } + + @Test void emptyFinalKeyAndSourceValidationOrder() { + for (boolean standalone : List.of(false, true)) { + String source = standalone ? "a: 1\n" : "parent: {x: 1}\n"; + byte[] bytes = source.getBytes(StandardCharsets.UTF_8); + List segments = standalone ? List.of("") : List.of("parent", ""); + for (boolean compound : List.of(false, true)) { + Value value = compound ? o("x", i("2")) : i("2"); + KtavException stringError = assertThrows(KtavException.class, + () -> lang.ktav.pure.PureKtav.insertValueSegments(source, segments, value)); + assertEquals("EditUnsupported", stringError.getError()); + assertEquals("empty key name is not representable", stringError.getBody()); + KtavException byteError = assertThrows(KtavException.class, + () -> lang.ktav.pure.PureKtav.insertValueSegments(bytes, segments, value)); + assertEquals("EditUnsupported", byteError.getError()); + assertEquals("empty key name is not representable", byteError.getBody()); + } + } + KtavException invalidSource = assertThrows(KtavException.class, + () -> lang.ktav.pure.PureKtav.insertValueSegments("a: [\n", List.of(""), i("2"))); + assertEquals("UnclosedCompound", invalidSource.getError()); + } +} diff --git a/lib/src/test/java/lang/ktav/PureRemoveRenameTest.java b/lib/src/test/java/lang/ktav/PureRemoveRenameTest.java new file mode 100644 index 0000000..42a5a76 --- /dev/null +++ b/lib/src/test/java/lang/ktav/PureRemoveRenameTest.java @@ -0,0 +1,219 @@ +package lang.ktav; + +import lang.ktav.pure.PureKtav; +import org.junit.jupiter.api.Test; + +import java.nio.charset.StandardCharsets; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.*; + +/** Regression contracts for pure removal and key renaming. */ +final class PureRemoveRenameTest { + private static Value i(String n) { return new Value.Int(n); } + private static Value o(Object... pairs) { + java.util.LinkedHashMap m = new java.util.LinkedHashMap<>(); + for (int n = 0; n < pairs.length; n += 2) m.put((String) pairs[n], (Value) pairs[n + 1]); + return new Value.Obj(m); + } + private static void both(String text, List segments, boolean rename) { + String expected = rename ? "a: {z: 1, y: 2}\nb: 3\n" : "a: {y: 2}\nb: 3\n"; + Value tree = rename ? o("a", o("z", i("1"), "y", i("2")), "b", i("3")) : o("a", o("y", i("2")), "b", i("3")); + String actual = rename ? PureKtav.renameKey(text, "a.x", "z") : PureKtav.removeValue(text, "a.x"); + assertEquals(expected, actual); + assertEquals(tree, PureKtav.loads(actual)); + String bySegments = rename ? PureKtav.renameKeySegments(text.getBytes(StandardCharsets.UTF_8), segments, "z") : PureKtav.removeValueSegments(text.getBytes(StandardCharsets.UTF_8), segments); + assertEquals(actual, bySegments); + } + + @Test void removeExactSemanticsAndOverloads() { + String src = "a: {x: 1, y: 2}\nb: 3\n"; + both(src, List.of("a", "x"), false); + assertEquals("b: 2\n", PureKtav.removeValue("a: 1\nb: 2\n".getBytes(StandardCharsets.UTF_8), "a")); + String eofSecond = "a: 1\nb: 2"; + String eofDeleted = PureKtav.removeValue(eofSecond, "b"); + assertEquals("a: 1", eofDeleted); + assertEquals(o("a", i("1")), PureKtav.loads(eofDeleted)); + assertEquals(eofDeleted, PureKtav.removeValueSegments(eofSecond, List.of("b"))); + assertEquals(o("a", i("1")), PureKtav.loads(PureKtav.removeValueSegments(eofSecond.getBytes(StandardCharsets.UTF_8), List.of("b")))); + assertEquals("a: {y: 2}\n", PureKtav.removeValueSegments("a: {x: 1, y: 2}\n", List.of("a", "x"))); + assertEquals("EditNotFound", assertThrows(KtavException.class, () -> PureKtav.removeValue("a: 1\n", "missing")).getError()); + assertEquals("EditNotFound", assertThrows(KtavException.class, () -> PureKtav.removeValueSegments("a: 1\n", List.of())).getError()); + assertEquals("EditInvalidPath", assertThrows(KtavException.class, () -> PureKtav.removeValue("a: 1\n", "a..b")).getError()); + assertEquals("a\\.b: 1\n", PureKtav.removeValueSegments("a\\.b: 1\nx: 2\n", List.of("x"))); + } + + @Test void removePreservesVerbatimDataMarkerInMultilineString() { + String source = "a: {\n s: ((\n## data\n))\n}\nb: 2\n"; + String expected = "b: 2\n"; + String byPath = PureKtav.removeValue(source, "a"); + assertEquals(expected, byPath); + assertEquals(o("b", i("2")), PureKtav.loads(byPath)); + String bySegments = PureKtav.removeValueSegments(source, List.of("a")); + assertEquals(expected, bySegments); + assertEquals(o("b", i("2")), PureKtav.loads(bySegments)); + String byPathBytes = PureKtav.removeValue(source.getBytes(StandardCharsets.UTF_8), "a"); + assertEquals(expected, byPathBytes); + assertEquals(o("b", i("2")), PureKtav.loads(byPathBytes)); + String bySegmentsBytes = PureKtav.removeValueSegments(source.getBytes(StandardCharsets.UTF_8), List.of("a")); + assertEquals(expected, bySegmentsBytes); + assertEquals(o("b", i("2")), PureKtav.loads(bySegmentsBytes)); + } + + @Test void renameOrderNoopCollisionAndLiteralSegments() { + String src = "a: {x: 1, y: 2}\nb: 3\n"; + both(src, List.of("a", "x"), true); + assertEquals("a: 1\nx: 2\n", PureKtav.renameKey("a: 1\nb: 2\n", "b", "x")); + String noop = "k:: 042\r\n"; + assertEquals(noop, PureKtav.renameKey(noop.getBytes(StandardCharsets.UTF_8), "k", "k")); + assertEquals("m: 1\n", PureKtav.renameKeySegments("x\\\\y: 1\n", List.of("x\\y"), "m")); + KtavException collision = assertThrows(KtavException.class, () -> PureKtav.renameKey("a: 1\nb: 2\n", "a", "b")); + assertEquals("EditAlreadyExists", collision.getError()); + assertNull(collision.getBody()); + assertEquals("EditNotFound", assertThrows(KtavException.class, () -> PureKtav.renameKeySegments("", List.of("k"), "x")).getError()); + assertEquals("EditInvalidPath", assertThrows(KtavException.class, () -> PureKtav.renameKey("a: 1\n", "a..b", "x")).getError()); + assertEquals("EditUnsupported", assertThrows(KtavException.class, () -> PureKtav.renameKey("items: [1]\n", "items.0", "x")).getError()); + assertEquals("EditUnsupported", assertThrows(KtavException.class, () -> PureKtav.renameKeySegments("items: [1]\n".getBytes(StandardCharsets.UTF_8), List.of("items", "0"), "x")).getError()); + } + + @Test void commentsUnsupportedAndAdjacentCommentsPreserved() { + String commented = "a: {\n ## inside a\n x: 1\n}\nb: 2\n"; + assertEquals("EditUnsupported", assertThrows(KtavException.class, () -> PureKtav.removeValue(commented, "a")).getError()); + String adjacent = "a: {\n before: 1\n ## between pairs\n x: 2\n ## after target\n after: 3\n}\n"; + String actual = PureKtav.removeValue(adjacent.getBytes(StandardCharsets.UTF_8), "a.x"); + assertTrue(actual.contains("## between pairs")); + assertTrue(actual.contains("## after target")); + assertEquals(o("a", o("before", i("1"), "after", i("3"))), PureKtav.loads(actual)); + String bySegments = PureKtav.removeValueSegments(adjacent, List.of("a", "x")); + assertEquals(actual, bySegments); + assertEquals(PureKtav.loads(actual), PureKtav.loads(bySegments)); + } + + @Test void dottedMaterializationKeepsEolEofBomAndArrayParent() { + String nested = "a: {\n b: {\n x: 1\n }\n}\nz: 2\n"; + String nestedActual = PureKtav.removeValue(nested.getBytes(StandardCharsets.UTF_8), "a.b.x"); + assertEquals(o("a", o("b", o()), "z", i("2")), PureKtav.loads(nestedActual)); + assertEquals(nestedActual, PureKtav.removeValueSegments(nested, List.of("a", "b", "x"))); + String eof = "a: {\n x: 1\n last: 2\n}"; + String eofActual = PureKtav.removeValue(eof, "a.last"); + assertEquals(o("a", o("x", i("1"))), PureKtav.loads(eofActual)); + assertEquals(eofActual, PureKtav.removeValueSegments(eof.getBytes(StandardCharsets.UTF_8), List.of("a", "last"))); + String bom = "\uFEFFa: {\n x: 1\n}\n"; + String bomActual = PureKtav.removeValue(bom.getBytes(StandardCharsets.UTF_8), "a.x"); + assertTrue(bomActual.startsWith("\uFEFF")); + assertEquals(o("a", o()), PureKtav.loads(bomActual)); + assertEquals(bomActual, PureKtav.removeValueSegments(bom, List.of("a", "x"))); + String array = "a: [\n {\n b: {\n x: 1\n }\n }\n]\n"; + String arrayActual = PureKtav.removeValue(array, "a.0.b.x"); + assertEquals(o("a", new Value.Arr(List.of(o("b", o())))), PureKtav.loads(arrayActual)); + assertEquals(arrayActual, PureKtav.removeValueSegments(array.getBytes(StandardCharsets.UTF_8), List.of("a", "0", "b", "x"))); + } + + @Test void dottedMaterializationBlockExactOverloads() { + String nested = "a: {\n b.c: 1\n}\n", nestedExpected = "a: {\n b: {}\n}\n"; + String nestedPath = PureKtav.removeValue(nested, "a.b.c"); + assertEquals(nestedExpected, nestedPath); + assertEquals(o("a", o("b", o())), PureKtav.loads(nestedPath)); + String nestedSegments = PureKtav.removeValueSegments(nested.getBytes(StandardCharsets.UTF_8), List.of("a", "b", "c")); + assertEquals(nestedExpected, nestedSegments); + assertEquals(PureKtav.loads(nestedPath), PureKtav.loads(nestedSegments)); + String array = "a: [\n {\n b.c: 1\n }\n]\n", arrayExpected = "a: [\n {\n b: {}\n }\n]\n"; + String arrayPath = PureKtav.removeValue(array.getBytes(StandardCharsets.UTF_8), "a.0.b.c"); + assertEquals(arrayExpected, arrayPath); + assertEquals(o("a", new Value.Arr(List.of(o("b", o())))), PureKtav.loads(arrayPath)); + String arraySegments = PureKtav.removeValueSegments(array, List.of("a", "0", "b", "c")); + assertEquals(arrayExpected, arraySegments); + assertEquals(PureKtav.loads(arrayPath), PureKtav.loads(arraySegments)); + } + + @Test void dottedMaterializationCrlfBomAndEofExact() { + String crlf = "a.b.c: 1\r\nz: 2\r\n", crlfExpected = "a.b: {}\r\nz: 2\r\n"; + String crlfPath = PureKtav.removeValue(crlf.getBytes(StandardCharsets.UTF_8), "a.b.c"); + assertEquals(crlfExpected, crlfPath); + assertEquals(o("a", o("b", o()), "z", i("2")), PureKtav.loads(crlfPath)); + assertEquals(crlfExpected, PureKtav.removeValueSegments(crlf, List.of("a", "b", "c"))); + assertEquals(o("a", o("b", o()), "z", i("2")), PureKtav.loads(PureKtav.removeValueSegments(crlf, List.of("a", "b", "c")))); + String bom = "\uFEFFa.b.c: 1\n", bomExpected = "\uFEFFa.b: {}\n"; + String bomPath = PureKtav.removeValue(bom, "a.b.c"); + assertEquals(bomExpected, bomPath); + assertEquals(o("a", o("b", o())), PureKtav.loads(bomPath)); + assertEquals(bomExpected, PureKtav.removeValueSegments(bom.getBytes(StandardCharsets.UTF_8), List.of("a", "b", "c"))); + assertEquals(o("a", o("b", o())), PureKtav.loads(PureKtav.removeValueSegments(bom.getBytes(StandardCharsets.UTF_8), List.of("a", "b", "c")))); + String eof = "a.b.c: 1", eofExpected = "a.b: {}"; + for (String actual : List.of( + PureKtav.removeValue(eof, "a.b.c"), + PureKtav.removeValue(eof.getBytes(StandardCharsets.UTF_8), "a.b.c"), + PureKtav.removeValueSegments(eof, List.of("a", "b", "c")), + PureKtav.removeValueSegments(eof.getBytes(StandardCharsets.UTF_8), List.of("a", "b", "c")))) { + assertEquals(eofExpected, actual); + assertEquals(o("a", o("b", o())), PureKtav.loads(actual)); + } + } + + @Test void deepInlineSecondKeyRenamePreservesOrderAndNoop() { + String src = "outer: {inner: {first: 1, second: 2, third: 3}, tail: 4}\n"; + String expected = "outer: {inner: {first: 1, renamed: 2, third: 3}, tail: 4}\n"; + assertEquals(expected, PureKtav.renameKey(src.getBytes(StandardCharsets.UTF_8), "outer.inner.second", "renamed")); + assertEquals(expected, PureKtav.renameKeySegments(src, List.of("outer", "inner", "second"), "renamed")); + assertEquals(o("outer", o("inner", o("first", i("1"), "renamed", i("2"), "third", i("3")), "tail", i("4"))), PureKtav.loads(PureKtav.renameKey(src.getBytes(StandardCharsets.UTF_8), "outer.inner.second", "renamed"))); + assertEquals(src, PureKtav.renameKey(src, "outer.inner.second", "second")); + assertEquals(src, PureKtav.renameKeySegments(src.getBytes(StandardCharsets.UTF_8), List.of("outer", "inner", "second"), "second")); + } + + @Test void dottedKeysAreNotPrunedAndSourceWins() { + String source = "a\\.b: 1\nx: 2\n"; + byte[] malformed = {'x', ':', ' ', (byte) 0xff}; + String expected = source.substring(0, source.indexOf("x: 2")); + String removed = PureKtav.removeValue(source, "x"); + assertEquals(expected, removed); + assertEquals(o("a.b", i("1")), PureKtav.loads(removed)); + assertEquals(expected, PureKtav.removeValueSegments(source, List.of("x"))); + String dotted = "a.b: 1\nx: 2\n", dottedRemoved = PureKtav.removeValue(dotted, "a.b"); + assertEquals("a: {}\nx: 2\n", dottedRemoved); + assertEquals(o("a", o(), "x", i("2")), PureKtav.loads(dottedRemoved)); + assertEquals("InvalidUtf8", assertThrows(KtavException.class, () -> PureKtav.removeValue(malformed, "\\q")).getError()); + assertEquals("InvalidUtf8", assertThrows(KtavException.class, () -> PureKtav.renameKeySegments(malformed, List.of(), "x")).getError()); + } + + @Test void rootInlineRemovalHandlesCommentsAndLexicalEdges() { + assertRootRemoval("\uFEFF## {\n {keep: 1, drop: 2} \u2003\n## ] tail\n", "drop", + "\uFEFF## {\n {keep: 1} \u2003\n## ] tail\n", o("keep", i("1"))); + assertRootRemoval("\uFEFF \t{keep: 1, drop: 2}\u2003\n## ] object tail\n", "drop", + "\uFEFF \t{keep: 1}\u2003\n## ] object tail\n", o("keep", i("1"))); + assertRootRemoval("\uFEFF \t[1, 2, 3,]\u2003\n## } array tail\n", "1", + "\uFEFF \t[1, 3,]\u2003\n## } array tail\n", new Value.Arr(List.of(i("1"), i("3")))); + assertRootRemoval("[1, 2, 3,]", "1", "[1, 3,]", new Value.Arr(List.of(i("1"), i("3")))); + assertRootRemoval("\uFEFF## {\n[1, 2, 3,] \u2003\n## } tail\n", "1", + "\uFEFF## {\n[1, 3,] \u2003\n## } tail\n", new Value.Arr(List.of(i("1"), i("3")))); + assertRootRemoval("{keep: don't, drop: 2}", "drop", "{keep: don't}", o("keep", new Value.Str("don't"))); + assertRootRemoval("{keep: a\"b, drop: 2}", "drop", "{keep: a\"b}", o("keep", new Value.Str("a\"b"))); + assertRootRemoval("{keep: a[b, drop: 2}", "drop", "{keep: a[b}", o("keep", new Value.Str("a[b"))); + assertRootRemoval("{\"a,b\": 1, \"x.y\": 2, drop: 3,}", "drop", + "{\"a,b\": 1, \"x.y\": 2,}", o("a,b", i("1"), "x.y", i("2"))); + assertRootRemoval("[a\\,b, x\\,y, drop,]", "2", "[a\\,b, x\\,y,]", + new Value.Arr(List.of(new Value.Str("a,b"), new Value.Str("x,y")))); + assertAllRemovalOverloadsThrow("{a.b: 1, a.c: 2}", List.of("a", "b"), "EditUnsupported"); + } + + private static void assertRootRemoval(String source, String path, String expected, Value expectedTree) { + String byPath = PureKtav.removeValue(source, path); + String byPathBytes = PureKtav.removeValue(source.getBytes(StandardCharsets.UTF_8), path); + String bySegments = PureKtav.removeValueSegments(source, List.of(path)); + String bySegmentsBytes = PureKtav.removeValueSegments(source.getBytes(StandardCharsets.UTF_8), List.of(path)); + assertEquals(expected, byPath); + assertEquals(expected, byPathBytes); + assertEquals(expected, bySegments); + assertEquals(expected, bySegmentsBytes); + assertEquals(expectedTree, PureKtav.loads(byPath)); + assertEquals(expectedTree, PureKtav.loads(byPathBytes)); + assertEquals(expectedTree, PureKtav.loads(bySegments)); + assertEquals(expectedTree, PureKtav.loads(bySegmentsBytes)); + } + + private static void assertAllRemovalOverloadsThrow(String source, List path, String error) { + assertEquals(error, assertThrows(KtavException.class, () -> PureKtav.removeValue(source, "a.b")).getError()); + assertEquals(error, assertThrows(KtavException.class, () -> PureKtav.removeValue(source.getBytes(StandardCharsets.UTF_8), "a.b")).getError()); + assertEquals(error, assertThrows(KtavException.class, () -> PureKtav.removeValueSegments(source, path)).getError()); + assertEquals(error, assertThrows(KtavException.class, () -> PureKtav.removeValueSegments(source.getBytes(StandardCharsets.UTF_8), path)).getError()); + } +} diff --git a/root-docs/CHANGELOG/unreleased/body-1.md b/root-docs/CHANGELOG/unreleased/body-1.md index 4f9bc18..9b87cdb 100644 --- a/root-docs/CHANGELOG/unreleased/body-1.md +++ b/root-docs/CHANGELOG/unreleased/body-1.md @@ -1,9 +1,15 @@ >>>>> lang=en ## Unreleased +- Add pure-backend `insertValue` / `insertValueSegments`, `removeValue` / `removeValueSegments`, and `renameKey` / `renameKeySegments`, matching the native source-edit APIs. Insert requires an existing Object parent; remove retains empty ancestors; rename preserves value and order. Successful splices verify the intended tree, and unsafe source shapes fail with `EditUnsupported`. Insert/rename collisions report `EditAlreadyExists`. These APIs prepare 0.9; package versions are unchanged. + >>>>> lang=ru ## Unreleased +- Добавлены чистые `insertValue` / `insertValueSegments`, `removeValue` / `removeValueSegments` и `renameKey` / `renameKeySegments`, соответствующие нативному API. Вставка требует существующего Object-родителя, удаление сохраняет пустых предков, переименование сохраняет значение и порядок. Успешный сплайс проверяет ожидаемое дерево; небезопасная форма исходника даёт `EditUnsupported`. Коллизии вставки/переименования — `EditAlreadyExists`. Это подготовка 0.9; версии пакетов не изменены. + >>>>> lang=zh ## Unreleased +- 新增纯后端 `insertValue` / `insertValueSegments`、`removeValue` / `removeValueSegments` 和 `renameKey` / `renameKeySegments`,对应原生源文本编辑 API。插入要求已存在的 Object 父节点,删除保留空祖先,重命名保留值和顺序。成功拼接验证预期树,无法安全处理的源形式返回 `EditUnsupported`;插入或重命名冲突返回 `EditAlreadyExists`。这些 API 为 0.9 做准备,包版本不变。 + diff --git a/root-docs/README/editing/body-1.md b/root-docs/README/editing/body-1.md index 53d2590..10ce294 100644 --- a/root-docs/README/editing/body-1.md +++ b/root-docs/README/editing/body-1.md @@ -23,6 +23,11 @@ branch expands — untouched nested branches stay inline. A replacement equal to the current value is a byte-identical no-op, even for noncanonical scalar spellings. +Paths are dotted (`key1.key2.0.key4`); inside a segment `\.` is a +literal dot and `\\` a literal backslash. The `*Segments` variants take +already-decoded literal segments: numeric segments are Object keys or +zero-based Array indexes, depending on the parent. + >>>>> lang=ru ### Правка исходного текста @@ -48,6 +53,11 @@ String out = Ktav.editValue("port: 8080\nhost: db\n", "port", равная текущему значению, — byte-identical no-op даже для неканонических написаний скаляров. +Пути разделены точками (`key1.key2.0.key4`); внутри сегмента `\.` — +буквальная точка, `\\` — обратная косая черта. Варианты `*Segments` +принимают декодированные буквальные сегменты: числовой сегмент — ключ +Object либо индекс Array с нуля в зависимости от родителя. + >>>>> lang=zh ### 编辑源文本 @@ -69,3 +79,7 @@ inline 包装才会展开,且只展开受影响的分支——未触及的嵌 inline。与当前值相等的替换是字节完全一致的 no-op,即使标量拼写不 规范也一样。 +路径以点分隔(`key1.key2.0.key4`);段内 `\.` 表示字面点号, +`\\` 表示字面反斜杠。`*Segments` 接收已解码的字面段;数字段按父节点 +类型解释为 Object 键或从零开始的 Array 索引。 + diff --git a/root-docs/README/editing/body-2.md b/root-docs/README/editing/body-2.md index e68cfa1..5bb2fb6 100644 --- a/root-docs/README/editing/body-2.md +++ b/root-docs/README/editing/body-2.md @@ -1,52 +1,74 @@ >>>>> lang=en -Paths are dotted (`key1.key2.0.key4`); inside a segment `\.` is a -literal dot and `\\` a literal backslash. `editValueSegments` takes -already-decoded literal segments instead — a numeric segment is a -string key inside an object and a zero-based index inside an array. -There is no create, remove, or rename: only replacement of an existing -value. - -Errors are structured: `EditInvalidPath` (body: the UTF-8 byte offset -inside the path argument where the defect is), `EditNotFound` (missing -key, out-of-bounds index, descent through a scalar, empty segments list), and -`EditUnsupported` (body: the reason — e.g. a noncontiguous -dotted-key/reopen target, a structural replacement that would drop -interior comment lines, or a value without a lossless representation -in the target context). Source-level problems still surface as the ordinary parse -envelopes. The pure backend exposes the same operations as -`PureKtav.editValue` / `PureKtav.editValueSegments` with identical -output. +Both `Ktav` and standalone `PureKtav` provide `insertValue`, +`removeValue`, and `renameKey`, plus their `*Segments` variants, with +String and byte-array sources. Insertion creates only a new final key +under an existing Object parent: no overwrite, implicit parents, or +Array insertion. Removal deletes an existing value/subtree or Array +element, shifts remaining elements, and never prunes empty ancestors. +Renaming changes only the final Object key to a literal name, preserving +value and order; the same name is a byte-identical no-op. Array indexes +cannot be renamed. Replacement still changes only an existing value. + +Edits splice source ranges rather than serialize the whole document. +Every success is reparsed and checked against the intended tree; +untouched bytes, comments, BOM, EOL/EOF conventions, and key spelling +remain unchanged. Inline layout expands only where needed for multiline +values, growth beyond max(100 Unicode scalars, original line width), or +String readability (at least four escapes and 25% overhead). Unsupported +source shapes fail explicitly rather than returning corrupted text. + +Errors: `EditInvalidPath` (body: UTF-8 path byte offset), `EditNotFound` +(missing target/parent, scalar descent, invalid Array index, empty decoded +path), `EditAlreadyExists` (insert or rename collision), and +`EditUnsupported` (body: reason, including noncontiguous dotted targets +or removal of a compound containing comments). Source parse errors win +over edit validation. Pure mode has no native dependency or fallback. >>>>> lang=ru -Пути — через точку (`key1.key2.0.key4`); внутри сегмента `\.` — -literal точка, `\\` — literal backslash. `editValueSegments` принимает -уже декодированные literal-сегменты: числовой сегмент — это ключ -внутри объекта и zero-based индекс внутри массива. Создание, удаление -и переименование не поддерживаются — только замена существующего -значения. - -Ошибки структурированы: `EditInvalidPath` (body: UTF-8 byte offset -внутри аргумента пути, где обнаружен дефект), `EditNotFound` -(отсутствующий ключ, индекс вне диапазона, спуск через скаляр, пустой -список сегментов) и `EditUnsupported` (body: причина — например noncontiguous-цель -из dotted-ключей и reopen, структурная замена, которая потеряла бы -комментарии внутри цели, или значение без lossless-представления в контексте цели). -Проблемы самого исходника по-прежнему приходят обычными parse -envelope'ами. Pure-бэкенд предоставляет те же операции — -`PureKtav.editValue` / `PureKtav.editValueSegments` — с идентичным -выводом. +`Ktav` и самостоятельный `PureKtav` предоставляют `insertValue`, +`removeValue`, `renameKey` и варианты `*Segments` для String и byte[]. +Вставка создаёт только новый конечный ключ существующего Object: +без перезаписи, неявных родителей или вставки в Array. Удаление убирает +существующее значение/поддерево либо элемент Array, сдвигает оставшиеся +элементы и не удаляет пустых предков. Переименование меняет только +последний ключ Object на буквальное имя, сохраняя значение и порядок; +прежнее имя даёт побайтовый no-op. Индексы Array не переименовываются. +Замена по-прежнему изменяет только существующее значение. + +Правки выполняются сплайсом диапазонов, а не сериализацией документа. +Каждый успешный результат повторно разбирается и сверяется с ожидаемым +деревом; нетронутые байты, комментарии, BOM, EOL/EOF и написание ключей +сохраняются. Inline-раскладка раскрывается лишь по необходимости: +многострочное значение, рост сверх max(100 Unicode-скаляров, исходная +ширина строки) либо читаемость String (не менее четырёх экранирований +и 25% накладных расходов). Неподдерживаемая форма исходника даёт явный +отказ, а не повреждённый текст. + +Ошибки: `EditInvalidPath` (body: UTF-8 byte offset пути), `EditNotFound` +(нет цели/родителя, спуск через скаляр, неверный индекс Array, пустой +декодированный путь), `EditAlreadyExists` (коллизия вставки/переименования) +и `EditUnsupported` (body: причина, включая несмежную dotted-цель или +удаление контейнера с комментариями). Ошибка разбора исходника имеет +приоритет. Чистому режиму не нужны native-зависимости или fallback. >>>>> lang=zh -路径以点分隔(`key1.key2.0.key4`);段内 `\.` 表示字面点号,`\\` -表示字面反斜杠。`editValueSegments` 直接接收已解码的字面段——数字段 -在对象中是字符串键,在数组中是从零开始的索引。不支持创建、删除或重 -命名——只支持替换已存在的值。 - -错误是结构化的:`EditInvalidPath`(body:路径参数中发现缺陷处的 -UTF-8 字节偏移)、`EditNotFound`(缺少键、索引越界、穿过标量下降、 -空路径段列表)和 `EditUnsupported`(body:原因——例如由 dotted 键与 reopen -拼成的非连续目标、会丢失容器内部注释的结构性替换,或无法在目标上下文中 -无损表示的值)。源文本本身的问题仍以普通解析错误 envelope 报告。 -纯 Java 后端提供相同操作——`PureKtav.editValue` / -`PureKtav.editValueSegments`,输出完全一致。 +`Ktav` 和独立的 `PureKtav` 均提供 `insertValue`、`removeValue`、 +`renameKey` 及 `*Segments` 变体,支持 String 和字节数组源文本。 +插入仅在已存在的 Object 父节点中创建新的末段键,不覆盖现有键, +不隐式创建父节点,也不插入 Array。删除移除现有值、子树或 Array +元素,后续元素前移,但不裁剪空祖先。重命名仅将末段 Object 键改为 +字面名称,保留值与顺序;名称不变时逐字节不变。不能重命名 Array +索引。替换仍仅修改现有值。 + +编辑拼接源文本范围,不重新序列化整个文档。每个成功结果都会重新 +解析并核对预期树;未触及的字节、注释、BOM、EOL/EOF 约定和键拼写 +保持不变。仅在多行值、增长超过 max(100 个 Unicode 标量,原行宽) +或 String 可读性需要时展开 inline 布局;可读性阈值为至少四个转义 +且开销至少 25%。不支持的源文本形式会明确失败,不返回损坏文本。 + +错误包括 `EditInvalidPath`(body:路径的 UTF-8 字节偏移)、 +`EditNotFound`(目标或父节点不存在、穿过标量、无效 Array 索引、 +空解码路径)、`EditAlreadyExists`(插入或重命名冲突)和 +`EditUnsupported`(body:原因,包括不连续 dotted 目标或删除含注释 +的容器)。源文本解析错误优先。纯模式不依赖原生库,也不会回退。 diff --git a/root-docs/README/pure-backend/body-1.md b/root-docs/README/pure-backend/body-1.md index 869b1dd..2357b63 100644 --- a/root-docs/README/pure-backend/body-1.md +++ b/root-docs/README/pure-backend/body-1.md @@ -25,6 +25,8 @@ For pure-only Gradle use, disable transitive dependencies: implementation("io.github.ktav-lang:ktav:0.8.1") { isTransitive = false } ``` +For Maven, exclude both `net.java.dev.jna:jna` and `com.fasterxml.jackson.core:jackson-core`; alternatively, use the library JAR directly. Pure-only runtime use requires JDK 17 and no third-party runtime libraries. Pure success and error paths use no JNA, Jackson, JUnit, native code, WASM, subprocesses, network access, or fallback. Native backend use requires its dependencies; retain normal dependency resolution for it. + >>>>> lang=ru ## Чисто-Java бэкенд @@ -52,6 +54,8 @@ implementation("io.github.ktav-lang:ktav:0.8.1") { isTransitive = false } implementation("io.github.ktav-lang:ktav:0.8.1") { isTransitive = false } ``` +В Maven исключите `net.java.dev.jna:jna` и `com.fasterxml.jackson.core:jackson-core`; альтернативно используйте JAR библиотеки напрямую. Для выполнения только чистого бэкенда нужен JDK 17, сторонние runtime-библиотеки не нужны. Успешные и ошибочные пути чистого бэкенда не используют JNA, Jackson, JUnit, нативный код, WASM, процессы, сеть или fallback. Нативному бэкенду нужны его зависимости; для него сохраняйте обычное разрешение зависимостей. + >>>>> lang=zh ## 纯 Java 后端 @@ -79,3 +83,12 @@ Gradle 纯后端用法可关闭传递依赖: implementation("io.github.ktav-lang:ktav:0.8.1") { isTransitive = false } ``` +Maven 请同时排除 `net.java.dev.jna:jna` 和 `com.fasterxml.jackson.core:jackson-core`;也可直接使用本库 JAR。纯后端运行需要 JDK 17,不需要第三方运行时库。纯后端的成功和错误路径均不使用 JNA、Jackson、JUnit、原生代码、WASM、子进程、网络或回退。原生后端用法需要其依赖;请为其保留常规依赖解析。 +该门面镜像 `Ktav` 的共享操作,并旨在生成相同的 `Value` 树和 +`KtavException` 信封;对于这些操作,代码可在两个后端之间无修改使用。 +源文本编辑包括替换、插入、删除和字面键重命名,支持文本路径和解码段。 +成功编辑保留未触及的源文本并验证预期树;不支持的源形式返回 +`EditUnsupported`。插入和重命名冲突返回 `EditAlreadyExists`。 +具体编辑契约见上文。没有全局后端 +开关:通过显式调用 `Ktav`(原生)或 `PureKtav`(纯)选择后端。 + diff --git a/root-docs/README/pure-backend/body-2.md b/root-docs/README/pure-backend/body-2.md index d261bc9..7bea945 100644 --- a/root-docs/README/pure-backend/body-2.md +++ b/root-docs/README/pure-backend/body-2.md @@ -1,9 +1,13 @@ >>>>> lang=en -For Maven, exclude both `net.java.dev.jna:jna` and `com.fasterxml.jackson.core:jackson-core`; alternatively, use the library JAR directly. Pure-only runtime use requires JDK 17 and no third-party runtime libraries. Pure success and error paths use no JNA, Jackson, JUnit, native code, WASM, subprocesses, network access, or fallback. Native backend use requires its dependencies; retain normal dependency resolution for it. - -The facade mirrors `Ktav` operation-for-operation and is designed to +The facade mirrors the shared operations of `Ktav` and is designed to produce the same `Value` tree and the same `KtavException` envelopes, -so code written against one backend reads unchanged against the other. There is no +so code written against one backend reads unchanged against the other +for those operations. Source editing includes replacement, insertion, +removal, and literal-key renaming, with textual and decoded-segment paths. +Successful edits preserve untouched source and verify the intended tree; +unsupported source shapes fail with `EditUnsupported`. Insert and rename +collisions report `EditAlreadyExists`. See the source-edit contract above. +There is no global backend switch: you choose a backend explicitly by calling `Ktav` (native) or `PureKtav` (pure). @@ -24,14 +28,16 @@ reference writer's documented layout (4-space indent, insertion order, § 5.9.10 key form selection). >>>>> lang=ru -В Maven исключите `net.java.dev.jna:jna` и `com.fasterxml.jackson.core:jackson-core`; альтернативно используйте JAR библиотеки напрямую. Для выполнения только чистого бэкенда нужен JDK 17, сторонние runtime-библиотеки не нужны. Успешные и ошибочные пути чистого бэкенда не используют JNA, Jackson, JUnit, нативный код, WASM, процессы, сеть или fallback. Нативному бэкенду нужны его зависимости; для него сохраняйте обычное разрешение зависимостей. - -Фасад повторяет `Ktav` операция в операцию и спроектирован так, чтобы -давать то же дерево `Value` и те же конверты `KtavException`, поэтому -код, написанный против одного бэкенда, против другого читается без -изменений. Глобального -переключателя бэкендов нет: бэкенд выбирается явно — вызовом `Ktav` -(нативный) или `PureKtav` (чистый). +Фасад повторяет общие операции `Ktav` и спроектирован так, чтобы +давать то же дерево `Value` и те же конверты `KtavException`; для этих +операций код можно переносить между бэкендами без изменений. Редактирование +включает замену, вставку, удаление и переименование буквального ключа, +с текстовыми путями и декодированными сегментами. Успех сохраняет нетронутый +исходник и проверяет ожидаемое дерево; неподдерживаемая форма даёт +`EditUnsupported`. Коллизии вставки и переименования — `EditAlreadyExists`. +Контракт редактирования описан выше. Глобального переключателя +бэкендов нет: бэкенд выбирается явно — вызовом `Ktav` (нативный) или +`PureKtav` (чистый). Чистый режим никогда не загружает и не скачивает нативную библиотеку — ни JNA, ни `ktav_cabi`, ни кэш-каталога, ни сети. Это правильный выбор @@ -50,12 +56,6 @@ reference writer's documented layout (4-space indent, insertion order, порядок вставки, выбор формы ключей по § 5.9.10). >>>>> lang=zh -Maven 请同时排除 `net.java.dev.jna:jna` 和 `com.fasterxml.jackson.core:jackson-core`;也可直接使用本库 JAR。纯后端运行需要 JDK 17,不需要第三方运行时库。纯后端的成功和错误路径均不使用 JNA、Jackson、JUnit、原生代码、WASM、子进程、网络或回退。原生后端用法需要其依赖;请为其保留常规依赖解析。 -该门面逐操作镜像 `Ktav`,其设计目标是产出相同的 `Value` 树和相同的 -`KtavException` 信封,因此针对一个后端编写的代码,换到另一个后端 -无需改动。没有全局后端开关:后端通过显式调用选择 —— `Ktav` -(原生)或 `PureKtav`(纯)。 - 纯模式从不加载或下载原生库 —— 没有 JNA、没有 `ktav_cabi`、没有缓存 目录、没有网络。它适合离线(air-gapped)环境、没有预编译原生资产的 平台,以及任何在乎纯 JVM 依赖的场景。原生后端仍是按参考实现调优的