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
10 changes: 5 additions & 5 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -116,18 +116,18 @@ jobs:
# Provenance (release guards NOT weakened — the target moved):
# Cargo.lock is generated in CI, NOT committed. The ktav core is
# the IMMUTABLE GIT PIN chosen by the user for the 0.9
# source-edit ABI (rev 447a00bd012e8d3f347c7e1eb59c3f0d9a78332f);
# source-edit/mutation ABI (rev 8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910);
# the TOML parse must show exactly one ktav [[package]] whose
# source is that exact git rev — a registry swap, a local-path
# override, a moved rev or a different branch fails the job here.
- name: Generate Cargo.lock and verify the immutable ktav git-core pin (447a00b, ABI 2)
- name: Generate Cargo.lock and verify the immutable ktav git-core pin (8b6b45f, ABI 2)
shell: bash
run: |
set -e
cargo generate-lockfile
python3 - <<'PY'
import sys, tomllib
REV = '447a00bd012e8d3f347c7e1eb59c3f0d9a78332f'
REV = '8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910'
with open('Cargo.lock', 'rb') as f:
data = tomllib.load(f)
pkgs = [p for p in data.get('package', []) if p.get('name') == 'ktav']
Expand All @@ -150,8 +150,8 @@ jobs:
with open('Cargo.toml', 'rb') as f:
ws = tomllib.load(f)
ktav = ws['workspace']['dependencies']['ktav']
if ktav.get('git') != 'https://github.com/ktav-lang/rust' or ktav.get('rev') != '447a00bd012e8d3f347c7e1eb59c3f0d9a78332f':
sys.exit('workspace ktav dependency is not the immutable 447a00b pin: %r' % (ktav,))
if ktav.get('git') != 'https://github.com/ktav-lang/rust' or ktav.get('rev') != '8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910':
sys.exit('workspace ktav dependency is not the immutable 8b6b45f pin: %r' % (ktav,))
print('workspace ktav dependency pinned:', ktav['rev'])
PY

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

- PHP source mutation now includes insert, remove and rename in both native and standalone pure backends. Insert adds a new final Object key without overwriting; remove targets an existing Object member or Array element without pruning ancestors (later Array elements shift); rename requires an existing final Object member and an absent destination key in that Object, preserving position and value. Insert requires an existing parent Object; Array insertion is unsupported. Native uses ABI 2 and the verified Rust core pin `8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910`; package versions remain unchanged and this unreleased 0.9 functionality is not part of published 0.8.1.

### 0.8.1

#### 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
25 changes: 21 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,19 +179,18 @@ stay ordered.

### Source-edit cookbook

These examples describe the unreleased 0.9 API, not the published 0.8.1 package. They replace existing values only: keys are not renamed, missing paths are not created, and entries are not removed. Each snippet is independent; Rust `?` assumes an enclosing `Result`-returning function. Go examples panic only for these fixed, known-valid inputs; applications should handle the returned error.
These examples describe the unreleased 0.9 API, not the published 0.8.1 package. Value replacement and insert/remove/rename are available through both pure and native backends. Each snippet is independent; Rust `?` assumes an enclosing `Result`-returning function. Go examples panic only for these fixed, known-valid inputs; applications should handle the returned error.

The binding examples use the standalone pure backend, without a native binary. Native entry points accept the same paths and values: `ktav.EditValue` (Go), `Ktav.editValue` (Java), `KtavApi.EditValue(..., KtavBackend.Native)` (C#), `Ktav::editValue` (PHP), the package's native/FFI exports (JS), and `ktav.edit_value` (Python). C-ABI backends require ABI 2; PyO3/N-API/WASM require the matching preparing-0.9 core. Bun/Deno FFI calls return promises: use `await`; pure/Node/WASM examples shown here are synchronous.

```php
use Ktav\PureBackend;
```
Use `PureBackend` or the native backend (`Ktav::`) for value replacement, insertion, removal, and renaming; both backends follow the same mutation contract. Textual paths split on dots, with `\.` for a literal dot and `\\` for a literal backslash; segment variants take decoded literal path segments. For rename, `newKey` is one decoded key, not a path. Bun/Deno FFI calls return promises and require `await`.

#### 1. Dotted deployment settings

Only the address changes; the comment, dotted form and neighbouring user entry remain byte-for-byte unchanged.

```php
use Ktav\PureBackend;
$source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n";
$updated = PureBackend::editValue($source, "targets.storagehost.address", "192.168.0.88:22");
```
Expand Down Expand Up @@ -292,6 +291,7 @@ n : +1
The returned string keeps the BOM and CRLF, and does not gain a final newline. Its escaped representation is shown to make the bytes visible.

```php
use Ktav\PureBackend;
$source = "\u{FEFF}port: 8080\r\nhost: db";
$updated = PureBackend::editValue($source, "port", 9090);
```
Expand All @@ -316,6 +316,23 @@ $updated = PureBackend::editValue("n: 1\n", "n", ['$i' => '9007199254740993']);
n: 9007199254740993
```

#### 9. Insert, remove and rename (textual and segment paths)

These new 0.9 insert/remove/rename operations are available through both pure and native backends and follow the same mutation contract. Insert adds a new final Object key without overwriting; removal targets an existing Object member or Array element without pruning ancestors (later Array elements shift); renaming requires an existing final Object member and a destination key absent from that same Object, preserving position and value. Insertion requires an existing parent Object; insertion into an Array is unsupported. Missing targets and invalid path/segment inputs are errors. Textual paths split on dots, with `\.` for a literal dot and `\\` for a literal backslash. Segment variants accept decoded literal path segments. `newKey` is one decoded key, not a path. Each snippet is independent.

```php
use Ktav\PureBackend;
$source = 'settings: {old: 1, "a.b": 3}' . "\n";
$inserted = PureBackend::insertValue($source, "settings.new", 2);
$insertedLiteral = PureBackend::insertValueSegments($source, ["settings", "added"], 2);
$removed = PureBackend::removeValue($source, "settings.old");
$removedLiteral = PureBackend::removeValueSegments($source, ["settings", "a.b"]);
$renamed = PureBackend::renameKey($source, "settings.old", "new.name");
$renamedLiteral = PureBackend::renameKeySegments($source, ["settings", "old"], "new.name");
```

An existing insertion key is an error, not an overwrite. Array elements shift after removal. Structural edits to containers with interior comments are unsupported because comments cannot be preserved losslessly. Inline dotted syntax is supported for value replacement, but structural insert/remove/rename requiring a synthetic, noncontiguous dotted path is unsupported. A trailing comma is preserved when the edit can be represented losslessly; the editor does not prune empty ancestors or promise lossless rewriting for every structural layout.

### Diagnostics and safe failures in 0.9

Source coordinates are UTF-8 byte offsets, including a BOM; spans are half-open `[start, end)`, and lines are 1-based. LF, lone CR and CRLF are handled, with CRLF counted as one terminator. A Unicode character may occupy several bytes.
Expand Down
4 changes: 3 additions & 1 deletion crates/cabi/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@
//! PHP consumer loads via `FFI::cdef`: `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`. Same signatures, ownership
//! `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`.
//! contract (`ktav_free(ptr, len)` frees exactly what a `ktav_*` call
//! returned), `0`/`1` return codes and JSON error envelopes as the
//! handwritten shim this crate carried before ktav 0.8. The wire format
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 @@ MINOR — ломающий.

## Unreleased

- Мутации исходника PHP теперь включают вставку, удаление и переименование как в native-, так и в самостоятельном pure-бэкенде. Вставка добавляет новый последний ключ Object без перезаписи; удаление затрагивает существующий член Object или элемент Array, не удаляя предков (последующие элементы Array сдвигаются); переименование требует существующий последний член Object и отсутствующий целевой ключ в этом Object, сохраняя позицию и значение. Для вставки нужен существующий родительский Object; вставка в Array не поддерживается. Native использует ABI 2 и проверенный pin ядра Rust `8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910`; версии пакетов не меняются, эта ещё не выпущенная функциональность 0.9 не входит в опубликованный 0.8.1.

### 0.8.1

#### Добавлено
Expand Down
25 changes: 21 additions & 4 deletions docs/ru/README.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -181,19 +181,18 @@ Object ИГНОРИРУЕТ порядок ключей (Rust IndexMap PartialEq

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

Примеры относятся к ещё не выпущенному API 0.9, а не к опубликованному пакету 0.8.1. Они заменяют только существующие значения: не переименовывают ключи, не создают отсутствующие пути и не удаляют записи. Фрагменты независимы; Rust `?` предполагает внешнюю функцию с результатом `Result`. В Go panic используется только для фиксированных корректных данных примера; приложение должно обработать возвращённую ошибку.
Замена значений и операции вставки, удаления и переименования доступны через pure- и native-бэкенды. Примеры относятся к ещё не выпущенному API 0.9, а не к опубликованному пакету 0.8.1. Фрагменты независимы; Rust `?` предполагает внешнюю функцию с результатом `Result`. В Go panic используется только для фиксированных корректных данных примера; приложение должно обработать возвращённую ошибку.

Примеры привязок используют самостоятельный pure-бэкенд без native-бинарника. Нативные точки входа принимают те же пути и значения: `ktav.EditValue` (Go), `Ktav.editValue` (Java), `KtavApi.EditValue(..., KtavBackend.Native)` (C#), `Ktav::editValue` (PHP), native/FFI-экспорты пакета (JS), `ktav.edit_value` (Python). C ABI требует версию 2; PyO3/N-API/WASM — совместимое ядро подготовки 0.9. FFI-вызовы Bun/Deno возвращают promise и требуют `await`; показанные pure/Node/WASM-варианты синхронны.

```php
use Ktav\PureBackend;
```
Для замены значения и операций вставки, удаления и переименования используйте `PureBackend` или native-бэкенд (`Ktav::`); оба бэкенда следуют одному контракту изменений. Текстовые пути разделяются по точкам; `\.` задаёт буквальную точку, а `\\` — буквальную обратную косую черту. Сегментные варианты принимают декодированные буквальные сегменты пути. При переименовании `newKey` — один декодированный ключ, а не путь. FFI-вызовы Bun/Deno возвращают promise и требуют `await`.

#### 1. Настройка развёртывания через dotted-ключ

Меняется только адрес; комментарий, dotted-форма и соседнее поле пользователя сохраняются байт-в-байт.

```php
use Ktav\PureBackend;
$source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n";
$updated = PureBackend::editValue($source, "targets.storagehost.address", "192.168.0.88:22");
```
Expand Down Expand Up @@ -294,6 +293,7 @@ n : +1
Результат сохраняет BOM и CRLF, не добавляя финальный перевод строки. Экранированное представление делает эти байты видимыми.

```php
use Ktav\PureBackend;
$source = "\u{FEFF}port: 8080\r\nhost: db";
$updated = PureBackend::editValue($source, "port", 9090);
```
Expand All @@ -318,6 +318,23 @@ $updated = PureBackend::editValue("n: 1\n", "n", ['$i' => '9007199254740993']);
n: 9007199254740993
```

#### 9. Вставка, удаление и переименование (текстовые пути и сегменты)

Новые операции вставки, удаления и переименования API 0.9 доступны через pure- и native-бэкенды и следуют одному контракту изменений. Вставка добавляет новый последний ключ Object без перезаписи; удаление удаляет существующий член Object или элемент Array, не удаляя предков (последующие элементы Array сдвигаются); переименование требует существующий последний член Object и отсутствующий целевой ключ в том же Object, сохраняя позицию и значение. Для вставки родительский путь должен вести к существующему Object; вставка в Array не поддерживается. Отсутствующие цели и некорректный ввод путей/сегментов завершаются ошибкой. Текстовый путь разделяется по точкам; `\.` задаёт буквальную точку, `\\` — буквальную обратную косую черту. Сегментные варианты принимают декодированные буквальные сегменты пути. `newKey` — один декодированный ключ, а не путь. Каждый пример независим.

```php
use Ktav\PureBackend;
$source = 'settings: {old: 1, "a.b": 3}' . "\n";
$inserted = PureBackend::insertValue($source, "settings.new", 2);
$insertedLiteral = PureBackend::insertValueSegments($source, ["settings", "added"], 2);
$removed = PureBackend::removeValue($source, "settings.old");
$removedLiteral = PureBackend::removeValueSegments($source, ["settings", "a.b"]);
$renamed = PureBackend::renameKey($source, "settings.old", "new.name");
$renamedLiteral = PureBackend::renameKeySegments($source, ["settings", "old"], "new.name");
```

Вставка при существующем ключе завершается ошибкой, а не перезаписью. Элементы Array после удаления сдвигаются. Структурные изменения контейнеров с внутренними комментариями не поддерживаются, поскольку комментарии нельзя сохранить без потерь. Встроенная dotted-форма поддерживается для замены значения, но структурные вставка/удаление/переименование, требующие синтетического непоследовательного dotted-пути, не поддерживаются. Конечная запятая сохраняется, если изменение можно представить без потерь; редактор не удаляет пустых предков и не гарантирует без потерь переписывать любую структурную раскладку.

### Диагностика и безопасные отказы в 0.9

Координаты исходника — байтовые смещения UTF-8 с учётом BOM; spans полуоткрыты `[start, end)`, строки нумеруются с 1. Поддерживаются LF, отдельный CR и CRLF; CRLF считается одним переводом строки. Один Unicode-символ может занимать несколько байтов.
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 @@ -23,6 +23,8 @@ MINOR 递增即破坏性变更。

## Unreleased

- PHP 源文本修改现已在 native 和独立 pure 后端中支持插入、删除及重命名。插入会添加新的最后一个 Object 键而不覆盖已有键;删除现有 Object 成员或 Array 元素但保留祖先(后续 Array 元素会移位);重命名要求最后一个 Object 成员存在且同一 Object 中目标键不存在,同时保留位置和值。插入要求父级是现有 Object;不支持向 Array 插入。Native 使用 ABI 2 及已验证的 Rust 核心 pin `8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910`;包版本不变,这些尚未发布的 0.9 功能不属于已发布的 0.8.1。

### 0.8.1

#### 新增
Expand Down
Loading
Loading