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
60 changes: 60 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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=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')
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

Expand Down Expand Up @@ -146,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()
Expand Down Expand Up @@ -244,9 +286,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=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')
PY

- name: Empty-input tests against the real debug artifact
env:
KTAV_LIB_PATH: ${{ github.workspace }}/target/debug/libktav_cabi.so
Expand Down
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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 = "8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910" }
serde = { version = "1", features = ["derive"] }
serde_json = { version = "1", features = ["preserve_order"] }
indexmap = "2"
Expand Down
54 changes: 36 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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).

Expand Down
8 changes: 6 additions & 2 deletions crates/cabi/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/ru/CHANGELOG.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@

## Unreleased

- Добавлены чистые `insertValue` / `insertValueSegments`, `removeValue` / `removeValueSegments` и `renameKey` / `renameKeySegments`, соответствующие нативному API. Вставка требует существующего Object-родителя, удаление сохраняет пустых предков, переименование сохраняет значение и порядок. Успешный сплайс проверяет ожидаемое дерево; небезопасная форма исходника даёт `EditUnsupported`. Коллизии вставки/переименования — `EditAlreadyExists`. Это подготовка 0.9; версии пакетов не изменены.

## 0.8.1 — 2026-10-22

### Добавлено
Expand Down
63 changes: 40 additions & 23 deletions docs/ru/README.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

### Практические примеры правки исходника

Expand Down Expand Up @@ -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`, ни кэш-каталога, ни сети. Это правильный выбор
Expand Down
2 changes: 2 additions & 0 deletions docs/zh/CHANGELOG.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

### 新增
Expand Down
Loading
Loading