Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@
# `git status` from Windows clients.
* text=auto eol=lf

# Polydoc требует пустую строку в конце промежуточных source parts.
root-docs/**/body-*.md whitespace=-blank-at-eof

# Windows-only scripts must stay CRLF — cmd.exe refuses to parse .bat
# files with LF-only endings.
*.bat text eol=crlf
Expand Down
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@ This changelog tracks **binding releases**, not changes to the Ktav format
itself — for the latter see
[`ktav-lang/spec`](https://github.com/ktav-lang/spec/blob/main/CHANGELOG.md).

## Unreleased — 0.9 preparation

- Add native and standalone pure editing by textual path or literal segments: source splicing, preserved container forms, minimal readability transitions, comment protection, byte-identical no-op and semantic verification.
- Apply 0.9 source diagnostics and the pinned 412-case conformance corpus, including 72 diagnostic fixtures with raw UTF-8 byte locations and EOF opener spans.
- Native uses the immutable preparing-0.9 core and C ABI 2; pure remains independent of native binaries. Package versions are unchanged; this functionality is not published in 0.8.1.

## Unreleased

## 0.8.1 — 2026-10-22
Expand Down
3 changes: 2 additions & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ repository = "https://github.com/ktav-lang/java"
rust-version = "1.71"

[workspace.dependencies]
ktav = ">=0.8.1, <0.9"
# Подготовка 0.9: immutable core pin с source-edit и ABI 2; пакет ещё не опубликован.
ktav = { git = "https://github.com/ktav-lang/rust", rev = "447a00bd012e8d3f347c7e1eb59c3f0d9a78332f" }
serde = { version = "1", features = ["derive"] }
serde_json = { version = "1", features = ["preserve_order"] }
indexmap = "2"
Expand Down
44 changes: 44 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,50 @@ equals `Ktav.emitCanonical(Ktav.loads(src))`. The stronger condition is
deliberate: blank lines are no more part of the `Value` model than
comments are, so the canonical writer drops them and `format` does not.

> **Unreleased (0.9 preparation):** These editing APIs and updated diagnostics are not included in published 0.8.1 packages. Native backends require the pinned 0.9 core (C ABI 2 for C-FFI); pure backends remain standalone.

### Editing source text

`Ktav.editValue()` replaces an **existing** value in Ktav source text
and returns new source text — a lossless, byte-level splice, not a
parse→render round-trip:

```java
String out = Ktav.editValue("port: 8080\nhost: db\n", "port",
new Value.Int("9090"));
// port: 9090
// host: db
```

Only the target's bytes change. Comments, blank lines, key spelling
and order, the BOM, and the document's LF / CR / CRLF style outside the
effective edit are preserved exactly. Dotted, inline, and block forms
survive as they are written; inline wrappers expand only when the
replacement would hurt readability (a multiline string, line growth
past `max(100 Unicode scalar values, the old physical line length)`, or
a replacement needing many escape sequences), and only the touched
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. `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 path), and
`EditUnsupported` (body: the reason — e.g. a noncontiguous
dotted-key/reopen target, a structural replacement that would drop
interior comment lines, or a multiline string containing a bare `))`
line). 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.

### Errors

`KtavException` is thrown on any parse or render failure. Beyond a
Expand Down
6 changes: 6 additions & 0 deletions docs/ru/CHANGELOG.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@
формата Ktav — для последнего см.
[`ktav-lang/spec`](https://github.com/ktav-lang/spec/blob/main/CHANGELOG.md).

## Ещё не выпущено — подготовка 0.9

- Добавлено редактирование по текстовому пути или буквальным сегментам в native- и самостоятельном pure-backend: source splice, сохранение форм контейнеров, минимальные переходы читаемости, защита комментариев, byte-identical no-op и семантическая проверка.
- Применена диагностика исходника 0.9 и закреплён corpus из 412 фикстур, включая 72 диагностические фикстуры с позициями сырых байтов UTF-8 и EOF spans от opener.
- Native использует immutable ядро подготовки 0.9 и C ABI 2; pure не требует native-бинарников. Версии пакетов не менялись; функционал не опубликован в 0.8.1.

## Unreleased

## 0.8.1 — 2026-10-22
Expand Down
44 changes: 44 additions & 0 deletions docs/ru/README.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,50 @@ System.out.print(Ktav.format("## the server\nserver: {host: a, port: 80}\n"));
пустые строки входят в модель `Value` не больше, чем комментарии,
поэтому канонический writer их отбрасывает, а `format` — нет.

> **Ещё не выпущено (подготовка 0.9):** Эти API редактирования и обновлённая диагностика не входят в опубликованные пакеты 0.8.1. Native-backend требует закреплённое ядро 0.9 (C ABI 2 для C-FFI); pure-backend остаётся самостоятельным.

### Правка исходного текста

`Ktav.editValue()` заменяет **существующее** значение в Ktav-исходном
тексте и возвращает новый исходный текст — это lossless-сплайс на
уровне байтов, а не круг parse→render:

```java
String out = Ktav.editValue("port: 8080\nhost: db\n", "port",
new Value.Int("9090"));
// port: 9090
// host: db
```

Меняются только байты цели. Комментарии, пустые строки, написание и
порядок ключей, BOM и стиль LF / CR / CRLF вне эффективной правки
сохраняются дословно. Dotted-, inline- и блочные формы переживают
правку как написано; inline-обёртки раскрываются только тогда, когда
замена ухудшает читаемость (многострочная строка, рост строки сверх
`max(100 Unicode scalar values, прежняя длина строки)`, замена,
требующая множества escape-последовательностей), и раскрывается только
затронутая ветвь — нетронутые вложенные ветви остаются inline. Замена,
равная текущему значению, — 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, структурная замена, которая потеряла бы
комментарии внутри цели, или многострочная строка со строкой `))`).
Проблемы самого исходника по-прежнему приходят обычными parse
envelope'ами. Pure-бэкенд предоставляет те же операции —
`PureKtav.editValue` / `PureKtav.editValueSegments` — с идентичным
выводом.

### Ошибки

`KtavException` бросается на любой ошибке разбора или рендеринга. Помимо
Expand Down
6 changes: 6 additions & 0 deletions docs/zh/CHANGELOG.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,12 @@ MINOR 递增视为破坏性变更。
本 changelog 跟踪 **绑定发布**,不覆盖 Ktav 格式自身的变更 ——
后者见 [`ktav-lang/spec`](https://github.com/ktav-lang/spec/blob/main/CHANGELOG.md)。

## 尚未发布 — 0.9 准备版本

- 新增原生及独立纯实现的路径编辑,支持点分文本或字面路径段:源文本拼接、保留容器形式、最小可读性展开、注释保护、逐字节 no-op 及语义验证。
- 应用 0.9 源诊断及固定的 412 个一致性 fixture,包括 72 个诊断 fixture,检查原始 UTF-8 字节位置及从起始标记到 EOF 的区间。
- 原生后端使用不可变的 0.9 准备核心及 C ABI 2;纯实现不需要原生二进制。包版本不变,这些功能尚未包含在已发布的 0.8.1 中。

## Unreleased

## 0.8.1 — 2026-10-22
Expand Down
35 changes: 35 additions & 0 deletions docs/zh/README.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,41 @@ System.out.print(Ktav.format("## the server\nserver: {host: a, port: 80}\n"));
与注释一样都不属于 `Value` 模型,所以规范 writer 会丢弃它们,而
`format` 不会。

> **尚未发布(0.9 准备版本):** 这些编辑 API 和更新后的诊断不包含在已发布的 0.8.1 包中。原生后端需要固定的 0.9 核心(C-FFI 使用 C ABI 2);纯实现仍完全独立。

### 编辑源文本

`Ktav.editValue()` 替换 Ktav 源文本中**已存在**的值并返回新的源文本
—— 这是字节级的无损拼接(splice),而不是 parse→render 往返:

```java
String out = Ktav.editValue("port: 8080\nhost: db\n", "port",
new Value.Int("9090"));
// port: 9090
// host: db
```

只有目标的字节会改变。注释、空行、键的拼写与顺序、BOM 以及有效编辑
范围之外的 LF / CR / CRLF 行尾风格都原样保留。dotted、inline 和块
形式按原样保留;仅当替换会损害可读性时(多行字符串、行长超过
`max(100 个 Unicode 标量值, 原物理行长)`、或需要大量转义序列的替换),
inline 包装才会展开,且只展开受影响的分支——未触及的嵌套分支保持
inline。与当前值相等的替换是字节完全一致的 no-op,即使标量拼写不
规范也一样。

路径以点分隔(`key1.key2.0.key4`);段内 `\.` 表示字面点号,`\\`
表示字面反斜杠。`editValueSegments` 直接接收已解码的字面段——数字段
在对象中是字符串键,在数组中是从零开始的索引。不支持创建、删除或重
命名——只支持替换已存在的值。

错误是结构化的:`EditInvalidPath`(body:路径参数中发现缺陷处的
UTF-8 字节偏移)、`EditNotFound`(缺少键、索引越界、穿过标量下降、
空路径)和 `EditUnsupported`(body:原因——例如由 dotted 键与 reopen
拼成的非连续目标、会丢失容器内部注释的结构性替换,或包含独立成行的
`))` 的多行字符串)。源文本本身的问题仍以普通解析错误 envelope 报告。
纯 Java 后端提供相同操作——`PureKtav.editValue` /
`PureKtav.editValueSegments`,输出完全一致。

### 错误

解析或渲染失败时抛出 `KtavException`。除了人类可读的 `getMessage()`
Expand Down
119 changes: 119 additions & 0 deletions lib/src/main/java/lang/ktav/Ktav.java
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
import lang.ktav.internal.WireJson;

import java.nio.charset.StandardCharsets;
import java.util.List;

/**
* Public facade for the Ktav configuration format. Thin wrapper around
Expand Down Expand Up @@ -232,6 +233,124 @@ public static String nativeVersion() {
return v == null ? "" : v;
}

// ------------------------------------------------------------------
// Lossless source edits (spec 0.9)
// ------------------------------------------------------------------

/**
* Replace an existing value addressed by the textual dotted path
* ({@code key1.key2.0.key4}; {@code \.} literal dot, {@code \\}
* literal backslash) with {@code replacement}, splicing only the
* target's bytes. See {@link lang.ktav.pure.PureKtav#editValue} for
* the full contract; the native and pure backends produce identical
* output.
*
* @throws KtavException {@code EditInvalidPath} (body: UTF-8 byte
* offset into the path), {@code EditNotFound},
* {@code EditUnsupported}, or an ordinary parse envelope
*/
public static String editValue(String src, String path,
Value replacement) {
return editValue(bytes(src, "src"), bytes(path, "path"),
replacement, false);
}

/** Byte-level variant of {@link #editValue(String, String, Value)}. */
public static String editValue(byte[] src, String path,
Value replacement) {
return editValue(src, bytes(path, "path"), replacement, false);
}

/**
* {@link #editValue(String, String, Value)} with pre-decoded literal
* segments (no additional unescaping; numeric segment = object key /
* zero-based ASCII-digit array index).
*/
public static String editValueSegments(String src,
List<String> segments, Value replacement) {
return editValue(bytes(src, "src"), WireJson.encodePath(segments),
replacement, true);
}

/** Byte-level variant of {@link #editValueSegments(String, List, Value)}. */
public static String editValueSegments(byte[] src,
List<String> segments, Value replacement) {
return editValue(src, WireJson.encodePath(segments), replacement,
true);
}

private static byte[] bytes(String s, String arg) {
if (s == null) {
throw new NullPointerException(arg);
}
return s.getBytes(StandardCharsets.UTF_8);
}

private static String editValue(byte[] src, byte[] path,
Value replacement, boolean segments) {
if (src == null) {
throw new NullPointerException("src");
}
if (replacement == null) {
throw new NullPointerException("replacement");
}
byte[] replacementWire = WireJson.encode(replacement);
NativeLib lib = NativeLib.get();

try (Memory srcMem = new Memory(Math.max(1, src.length));
Memory pathMem = new Memory(Math.max(1, path.length));
Memory replMem = new Memory(
Math.max(1, replacementWire.length))) {
if (src.length > 0) {
srcMem.write(0, src, 0, src.length);
}
if (path.length > 0) {
pathMem.write(0, path, 0, path.length);
}
if (replacementWire.length > 0) {
replMem.write(0, replacementWire, 0, replacementWire.length);
}

PointerByReference outBuf = new PointerByReference();
LongByReference outLen = new LongByReference();
PointerByReference outErr = new PointerByReference();
LongByReference outErrLen = new LongByReference();

int rc;
try {
rc = segments
? lib.ktav_edit_value_segments(srcMem, src.length,
pathMem, path.length, replMem,
replacementWire.length, outBuf, outLen,
outErr, outErrLen)
: lib.ktav_edit_value(srcMem, src.length, pathMem,
path.length, replMem, replacementWire.length,
outBuf, outLen, outErr, outErrLen);
} catch (UnsatisfiedLinkError | NoSuchMethodError e) {
// An old native binary simply lacks the 0.9 symbols:
// report that clearly instead of silently falling back.
throw new KtavException(
"the loaded ktav_cabi native library does not provide"
+ " the source-edit entry points; a 0.9 (or"
+ " newer) native library is required",
e);
}

if (rc != 0) {
byte[] payload = copyAndFreeBytes(lib, outErr.getValue(),
outErrLen.getValue());
if (payload.length == 0) {
throw new KtavException(
"native call failed with code " + rc);
}
throw KtavException.fromEnvelope(ErrorEnvelope.parse(payload));
}

return new String(copyAndFreeBytes(lib, outBuf.getValue(),
outLen.getValue()), StandardCharsets.UTF_8);
}
}

private enum NativeOp {
LOADS,
LOADS_STRICT,
Expand Down
47 changes: 46 additions & 1 deletion lib/src/main/java/lang/ktav/internal/NativeLib.java
Original file line number Diff line number Diff line change
Expand Up @@ -72,16 +72,61 @@ int ktav_format(
PointerByReference outErr,
LongByReference outErrLen);

int ktav_edit_value(
Pointer src,
long srcLen,
Pointer path,
long pathLen,
Pointer replacement,
long replacementLen,
PointerByReference outBuf,
LongByReference outLen,
PointerByReference outErr,
LongByReference outErrLen);

int ktav_edit_value_segments(
Pointer src,
long srcLen,
Pointer path,
long pathLen,
Pointer replacement,
long replacementLen,
PointerByReference outBuf,
LongByReference outLen,
PointerByReference outErr,
LongByReference outErrLen);

void ktav_free(Pointer ptr, long len);

String ktav_version();

/** ABI version reported by the loaded native library. */
int ktav_abi_version();

/**
* The ABI version this binding is built against. 0.9 raises it from
* 1 to 2 (the exported set grew by the source-edit symbols); an
* ABI-1 native binary is REJECTED with a clear version-mismatch
* error — never silently used, never hidden behind a pure fallback.
*/
int EXPECTED_ABI_VERSION = 2;

final class Holder {
private static final NativeLib INSTANCE = loadSingleton();

private static NativeLib loadSingleton() {
String path = NativeLoader.resolve();
return Native.load(path, NativeLib.class);
NativeLib lib = Native.load(path, NativeLib.class);
int abi = lib.ktav_abi_version();
if (abi != EXPECTED_ABI_VERSION) {
throw new IllegalStateException(
"ktav_cabi ABI version mismatch: loaded library "
+ "reports ABI " + abi + " but this binding"
+ " requires ABI " + EXPECTED_ABI_VERSION
+ " (source-edit entry points need the 0.9"
+ " native library): " + path);
}
return lib;
}

private Holder() {
Expand Down
Loading
Loading