From 13c144329579d116012b6e2e7e20690cef3100b1 Mon Sep 17 00:00:00 2001 From: Marat K Date: Sun, 25 Oct 2026 22:22:38 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=BE=D0=BF=D0=B8=D1=81=D0=B0=D1=82?= =?UTF-8?q?=D1=8C=20Python=20source-edit=200.9=20=D1=81=20=D0=BF=D1=80?= =?UTF-8?q?=D0=B8=D0=BC=D0=B5=D1=80=D0=B0=D0=BC=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Добавить восемь рецептов и byte diagnostics EN/RU/ZH. Перенести новые функции из раздела 0.8.1 в отдельный unreleased 0.9; сохранить исторические записи и runtime API. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 48 +++--- README.md | 155 +++++++++++++++++- docs/ru/CHANGELOG.ru.md | 50 +++--- docs/ru/README.ru.md | 155 +++++++++++++++++- docs/zh/CHANGELOG.zh.md | 42 +++-- docs/zh/README.zh.md | 155 +++++++++++++++++- root-docs/CHANGELOG/manifest.js | 1 + .../body-3.md => source-edit09/body-1.md} | 18 ++ root-docs/CHANGELOG/source-edit09/meta.js | 7 + root-docs/CHANGELOG/unreleased-added/meta.js | 2 +- root-docs/README/diagnostics09/body-1.md | 39 +++++ root-docs/README/diagnostics09/meta.js | 7 + root-docs/README/editing-cookbook/body-1.md | 84 ++++++++++ root-docs/README/editing-cookbook/body-2.md | 84 ++++++++++ root-docs/README/editing-cookbook/body-3.md | 93 +++++++++++ root-docs/README/editing-cookbook/body-4.md | 87 ++++++++++ root-docs/README/editing-cookbook/body-5.md | 84 ++++++++++ root-docs/README/editing-cookbook/meta.js | 7 + root-docs/README/manifest.js | 2 + root-docs/README/source-edit/body-1.md | 12 +- 20 files changed, 1058 insertions(+), 74 deletions(-) rename root-docs/CHANGELOG/{unreleased-added/body-3.md => source-edit09/body-1.md} (76%) create mode 100644 root-docs/CHANGELOG/source-edit09/meta.js create mode 100644 root-docs/README/diagnostics09/body-1.md create mode 100644 root-docs/README/diagnostics09/meta.js create mode 100644 root-docs/README/editing-cookbook/body-1.md create mode 100644 root-docs/README/editing-cookbook/body-2.md create mode 100644 root-docs/README/editing-cookbook/body-3.md create mode 100644 root-docs/README/editing-cookbook/body-4.md create mode 100644 root-docs/README/editing-cookbook/body-5.md create mode 100644 root-docs/README/editing-cookbook/meta.js diff --git a/CHANGELOG.md b/CHANGELOG.md index 8dcd0e0..3b7e5cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,33 @@ For the format specification's own history, see underlying Rust implementation, see [`ktav-lang/rust`](https://github.com/ktav-lang/rust). +## Unreleased — 0.9 preparation + +- `ktav.edit_value(source, path, replacement)` and + `ktav.edit_value_segments(source, segments, replacement)` — lossless + in-place source edits (source-edit 0.9). Only the bytes of the target + value (plus inline wrappers the layout rules force to unfold) change; + comments, key spelling, blank lines, BOM and CR/LF/CRLF survive, and + an equal replacement is a byte-identical no-op. New exception family + `KtavEditError` with `KtavInvalidPathError` (`body` = decimal UTF-8 + byte offset into the path), `KtavNotFoundError`, and + `KtavUnsupportedError`; the same ten-field envelope, `error` is one + of `EditInvalidPath` / `EditNotFound` / `EditUnsupported`. +- Spec 0.9 corpus: the conformance runner now executes the + `versions/0.9/tests` fixtures (162 invalid — 72 new `diagnostics09` + EOF/malformed-UTF-8 diagnostics), validates `expected_location` + metadata (line, raw-byte `start`, exact `end` or `minimum_end`), and + feeds every `raw_bytes`-flagged fixture through the shared byte + boundary, so invalid UTF-8 raises the structured `InvalidUtf8` + envelope in both backends. +- `UnclosedCompound` errors now pin the opener: `line` and `line_text` + name the line that opened the innermost unclosed compound, and + `span` runs from that opener to end of input. + +### Documentation + +- Expand README examples for dotted and literal-key paths, mixed arrays, String/Integer identity, multiline unfolding, byte-identical no-op and BOM/CRLF/EOF preservation. Clarify 0.9 byte diagnostics, safe refusal, ABI 2 and standalone pure usage; these additions are not part of published 0.8.1. + ## [0.8.1] Synchronized with Ktav spec 0.8.1 and Rust core 0.8.1. New in this @@ -62,27 +89,6 @@ release: a complete pure-Python parser and generator, available as native platform wheels. It installs with no Rust toolchain, compiler or maturin and provides exactly the `ktav.pure` backend. -- `ktav.edit_value(source, path, replacement)` and - `ktav.edit_value_segments(source, segments, replacement)` — lossless - in-place source edits (source-edit 0.9). Only the bytes of the target - value (plus inline wrappers the layout rules force to unfold) change; - comments, key spelling, blank lines, BOM and CR/LF/CRLF survive, and - an equal replacement is a byte-identical no-op. New exception family - `KtavEditError` with `KtavInvalidPathError` (`body` = decimal UTF-8 - byte offset into the path), `KtavNotFoundError`, and - `KtavUnsupportedError`; the same ten-field envelope, `error` is one - of `EditInvalidPath` / `EditNotFound` / `EditUnsupported`. -- Spec 0.9 corpus: the conformance runner now executes the - `versions/0.9/tests` fixtures (162 invalid — 72 new `diagnostics09` - EOF/malformed-UTF-8 diagnostics), validates `expected_location` - metadata (line, raw-byte `start`, exact `end` or `minimum_end`), and - feeds every `raw_bytes`-flagged fixture through the shared byte - boundary, so invalid UTF-8 raises the structured `InvalidUtf8` - envelope in both backends. -- `UnclosedCompound` errors now pin the opener: `line` and `line_text` - name the line that opened the innermost unclosed compound, and - `span` runs from that opener to end of input. - ### Changed - Upgraded to Rust core 0.8.1 and spec 0.8.1 (published as the spec diff --git a/README.md b/README.md index 559ccdf..b17d29b 100644 --- a/README.md +++ b/README.md @@ -205,12 +205,163 @@ dotted/inline/block forms are kept, and an equal replacement is a byte-identical no-op — even for noncanonical spelling. Every successful patch is re-parsed and semantically verified. When no lossless patch exists (noncontiguous dotted/reopened targets, internal -comments under structural replacement, a `))` line inside a multiline -replacement) the call raises `KtavUnsupportedError` instead of +comments under structural replacement, an unrepresentable value in the +target context) the call raises `KtavUnsupportedError` instead of guessing. Long or multiline replacements unfold only the touched inline wrappers; untouched nested branches stay inline. Both the native and the pure backend implement the identical semantics. +### 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. + +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. + +```python +import ktav.pure as ktav +``` + +#### 1. Dotted deployment settings + +Only the address changes; the comment, dotted form and neighbouring user entry remain byte-for-byte unchanged. + +```python +source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n" +updated = ktav.edit_value(source, "targets.storagehost.address", "192.168.0.88:22") +``` + +Result: + +```ktav +## deployment +targets.storagehost.address: 192.168.0.88:22 +targets.storagehost.user: mcp-agent +``` + +#### 2. Literal dots: textual path or segments + +The quoted source key is literally `a.b`. The textual path escapes its dot; the segments call passes the decoded key directly. Both calls return the same result. + +```python +source = "\"a.b\": {port: 80}\n" +updated = ktav.edit_value(source, "a\\.b.port", 90) +same = ktav.edit_value_segments(source, ["a.b", "port"], 90) +``` + +Result: + +```ktav +"a.b": {port: 90} +``` + +#### 3. A leaf inside a mixed-form array + +`0` is an array index here. Inside an Object, the same segment would address the key named `0`; untouched containers remain inline. + +```python +source = "servers: [{host: old, keep: yes}, standby]\n" +updated = ktav.edit_value_segments(source, ["servers", "0", "host"], "new") +``` + +Result: + +```ktav +servers: [{host: new, keep: yes}, standby] +``` + +#### 4. A numeric-looking String stays a String + +The replacement is a String, not an Integer. The raw marker preserves that distinction. Supply a typed Integer when a numeric value is intended. + +```python +source = "port: 8080\n" +updated = ktav.edit_value(source, "port", "9090") +``` + +Result: + +```ktav +port:: 9090 +``` + +#### 5. Multiline replacement: expand only what is necessary + +The changed array expands with four-space indentation. The untouched object stays inline, and verbatim string contents are not reindented. + +```python +source = "a: [old, {keep: yes}]\n" +updated = ktav.edit_value(source, "a.0", "x\ny") +``` + +Result: + +```ktav +a: [ + (( +x +y + )) + {keep: yes} +] +``` + +#### 6. No-op preserves noncanonical spelling + +The Integer value is already 1. Equality returns the original bytes, including `+1` and the original separator spacing; readability thresholds are bypassed. + +```python +source = "n : +1\n" +updated = ktav.edit_value(source, "n", 1) +assert updated == source +``` + +Result: + +```ktav +n : +1 +``` + +#### 7. BOM, CRLF and an unterminated final line + +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. + +```python +source = "\ufeffport: 8080\r\nhost: db" +updated = ktav.edit_value(source, "port", 9090) +``` + +Result: + +```text +"\uFEFFport: 9090\r\nhost: db" +``` + +Expansion is deterministic: a multiline replacement, growth beyond `max(100, original line length)`, or at least four escapes with at least 25% encoding overhead for an individual replacement string. Width counts Unicode scalar values, not UTF-8 bytes or terminal columns. An already-long line without growth is kept. New levels use four spaces and the source EOL. If CR or a `))` data line prevents lossless standalone encoding, a valid inline candidate is retained; these characters do not automatically make every inline edit unsupported. + +#### 8. Exact Integer replacement + +The source Integer domain is signed 64-bit. This value exceeds JavaScript's safe-Number range but fits i64; use an exact host representation, not a rounded floating-point value. A typed Integer outside i64 cannot be preserved as an Integer in source and is refused instead of truncated. Use a String when a large identifier is text. Float identity distinguishes negative and positive zero; Object no-op equality ignores key order, while Array order remains significant. + +```python +updated = ktav.edit_value("n: 1\n", "n", 9007199254740993) +``` + +```ktav +n: 9007199254740993 +``` + +### 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. + +An unfinished `a: [\n` reports `UnclosedCompound`, line 1 and span `3..5`: the span begins at the innermost unmatched opener, not the start of its key or line. For raw bytes `61 3A 20 FF` (`a: ` followed by invalid UTF-8), validation reports `InvalidUtf8`, line 1 and a covering span `3..4`; `line_text` is null rather than fabricated by lossy decoding. UTF-8 validation precedes grammar processing. + +A malformed textual path, including an empty textual path or empty textual segment, is `EditInvalidPath`; its offset is measured in the path's UTF-8 bytes. An empty segments list, missing key, out-of-range index or scalar descent is `EditNotFound`. Object numeric segments remain keys; array indexes use ASCII digits, allow leading zeros and reject signs. + +Whole dotted/reopened intermediate objects may occupy several physical ranges and are `EditUnsupported`; their existing leaves can still be edited. Replacing a container must not discard interior comments. No failed call returns a partial patch or changes the supplied source. The returned text is re-parsed and semantically checked: the target must equal the replacement and the rest of the value tree must remain equal. + +For bindings, invalid source is reported with the ordinary parser envelope before path validation. Malformed wire payloads are `Message` errors without invented source coordinates. The wire envelope has `error`, `reason`, `line`, `line_text`, `span`, `path`, `body`, `canonical`, `spec_section` and `message`; host accessor names are documented in the errors section. `body` carries the decimal path-byte offset for `EditInvalidPath`, null for `EditNotFound`, and the refusal reason for `EditUnsupported`. + Unlike the JavaScript bindings, `canonical_from_source` buys you no extra numeric fidelity here — Python distinguishes `int` from `float`, so the Ktav Integer/Float distinction survives `loads`, and diff --git a/docs/ru/CHANGELOG.ru.md b/docs/ru/CHANGELOG.ru.md index 17da52d..60bebaf 100644 --- a/docs/ru/CHANGELOG.ru.md +++ b/docs/ru/CHANGELOG.ru.md @@ -12,6 +12,34 @@ реализация на Rust — в [`ktav-lang/rust`](https://github.com/ktav-lang/rust). +## Ещё не выпущено — подготовка 0.9 + +- `ktav.edit_value(source, path, replacement)` и + `ktav.edit_value_segments(source, segments, replacement)` — + lossless-правка исходника по месту (source-edit 0.9). Меняются только + байты целевого значения (плюс inline-обёртки, которые требует + раскрыть layout-правило); комментарии, написание ключей, пустые + строки, BOM и CR/LF/CRLF сохраняются, а совпадающая замена — + byte-identical no-op. Новое семейство исключений `KtavEditError` с + `KtavInvalidPathError` (`body` = десятичный UTF-8 byte offset в + путь), `KtavNotFoundError` и `KtavUnsupportedError`; тот же + десятипольный конверт, `error` — один из `EditInvalidPath` / + `EditNotFound` / `EditUnsupported`. +- Корпус spec 0.9: conformance runner исполняет fixtures из + `versions/0.9/tests` (162 invalid — 72 новых диагностики + `diagnostics09` EOF/битый UTF-8), проверяет метаданные + `expected_location` (line, raw-byte `start`, точный `end` или + `minimum_end`) и прогоняет все `raw_bytes`-fixture через общий + byte-boundary, так что битый UTF-8 даёт структурированный конверт + `InvalidUtf8` в обоих backend-ах. +- Ошибки `UnclosedCompound` теперь указывают открыватель: `line` и + `line_text` называют строку, открывшую ближайший незакрытый + контейнер, а `span` тянется от него до конца ввода. + +### Документация + +- Дополнены примеры README: dotted-пути и буквальные ключи, смешанные массивы, различие String/Integer, раскрытие многострочной замены, побайтовый no-op и сохранение BOM/CRLF/EOF. Уточнены байтовая диагностика 0.9, безопасные отказы, ABI 2 и самостоятельный pure-бэкенд; дополнения не относятся к опубликованному 0.8.1. + ## [0.8.1] Синхронизация со спецификацией Ktav 0.8.1 и Rust core 0.8.1. Главное в @@ -66,28 +94,6 @@ нативными платформенными wheel-ами. Он ставится без Rust toolchain, компилятора и maturin и предоставляет ровно backend `ktav.pure`. -- `ktav.edit_value(source, path, replacement)` и - `ktav.edit_value_segments(source, segments, replacement)` — - lossless-правка исходника по месту (source-edit 0.9). Меняются только - байты целевого значения (плюс inline-обёртки, которые требует - раскрыть layout-правило); комментарии, написание ключей, пустые - строки, BOM и CR/LF/CRLF сохраняются, а совпадающая замена — - byte-identical no-op. Новое семейство исключений `KtavEditError` с - `KtavInvalidPathError` (`body` = десятичный UTF-8 byte offset в - путь), `KtavNotFoundError` и `KtavUnsupportedError`; тот же - десятипольный конверт, `error` — один из `EditInvalidPath` / - `EditNotFound` / `EditUnsupported`. -- Корпус spec 0.9: conformance runner исполняет fixtures из - `versions/0.9/tests` (162 invalid — 72 новых диагностики - `diagnostics09` EOF/битый UTF-8), проверяет метаданные - `expected_location` (line, raw-byte `start`, точный `end` или - `minimum_end`) и прогоняет все `raw_bytes`-fixture через общий - byte-boundary, так что битый UTF-8 даёт структурированный конверт - `InvalidUtf8` в обоих backend-ах. -- Ошибки `UnclosedCompound` теперь указывают открыватель: `line` и - `line_text` называют строку, открывшую ближайший незакрытый - контейнер, а `span` тянется от него до конца ввода. - ### Changed - Обновление до Rust core 0.8.1 и spec 0.8.1 (опубликованы как каталог diff --git a/docs/ru/README.ru.md b/docs/ru/README.ru.md index 2608039..77fb589 100644 --- a/docs/ru/README.ru.md +++ b/docs/ru/README.ru.md @@ -206,12 +206,163 @@ dotted/inline/block-формы держатся, а совпадающая за byte-identical no-op, даже при неканоничном написании. Каждый успешный патч перепарсится и семантически проверяется. Когда lossless патча не существует (noncontiguous dotted/reopen-цели, внутренние -комментарии при структурной замене, строка `))` внутри multiline -замены), вызов бросает `KtavUnsupportedError`, а не угадывает. Длинные +комментарии при структурной замене, непредставимое в контексте цели +значение), вызов бросает `KtavUnsupportedError`, а не угадывает. Длинные и многострочные замены раскрывают только затронутые inline-обёртки; нетронутые ветки остаются inline. Native и pure backend реализуют идентичную семантику. +### Практические примеры правки исходника + +Примеры относятся к ещё не выпущенному 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-варианты синхронны. + +```python +import ktav.pure as ktav +``` + +#### 1. Настройка развёртывания через dotted-ключ + +Меняется только адрес; комментарий, dotted-форма и соседнее поле пользователя сохраняются байт-в-байт. + +```python +source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n" +updated = ktav.edit_value(source, "targets.storagehost.address", "192.168.0.88:22") +``` + +Результат: + +```ktav +## deployment +targets.storagehost.address: 192.168.0.88:22 +targets.storagehost.user: mcp-agent +``` + +#### 2. Буквальные точки: текстовый путь или сегменты + +Ключ исходника в кавычках буквально называется `a.b`. В текстовом пути точка экранируется; API сегментов получает декодированное имя напрямую. Оба вызова возвращают одинаковый результат. + +```python +source = "\"a.b\": {port: 80}\n" +updated = ktav.edit_value(source, "a\\.b.port", 90) +same = ktav.edit_value_segments(source, ["a.b", "port"], 90) +``` + +Результат: + +```ktav +"a.b": {port: 90} +``` + +#### 3. Лист внутри массива со смешанными формами + +Здесь `0` — индекс массива. В объекте такой же сегмент обозначал бы ключ с именем `0`; нетронутые контейнеры остаются inline. + +```python +source = "servers: [{host: old, keep: yes}, standby]\n" +updated = ktav.edit_value_segments(source, ["servers", "0", "host"], "new") +``` + +Результат: + +```ktav +servers: [{host: new, keep: yes}, standby] +``` + +#### 4. Похожая на число строка остаётся строкой + +Замена имеет тип String, а не Integer. Raw-маркер сохраняет это различие. Для числового значения передавайте типизированный Integer. + +```python +source = "port: 8080\n" +updated = ktav.edit_value(source, "port", "9090") +``` + +Результат: + +```ktav +port:: 9090 +``` + +#### 5. Многострочная замена: раскрывается только необходимое + +Изменённый массив раскрывается с отступом четыре пробела. Нетронутый объект остаётся inline, содержимое verbatim-строки не переотступается. + +```python +source = "a: [old, {keep: yes}]\n" +updated = ktav.edit_value(source, "a.0", "x\ny") +``` + +Результат: + +```ktav +a: [ + (( +x +y + )) + {keep: yes} +] +``` + +#### 6. No-op сохраняет неканоническое написание + +Значение Integer уже равно 1. Проверка равенства возвращает исходные байты, включая `+1` и пробелы разделителя; критерии читаемости не применяются. + +```python +source = "n : +1\n" +updated = ktav.edit_value(source, "n", 1) +assert updated == source +``` + +Результат: + +```ktav +n : +1 +``` + +#### 7. BOM, CRLF и последняя строка без перевода + +Результат сохраняет BOM и CRLF, не добавляя финальный перевод строки. Экранированное представление делает эти байты видимыми. + +```python +source = "\ufeffport: 8080\r\nhost: db" +updated = ktav.edit_value(source, "port", 9090) +``` + +Результат: + +```text +"\uFEFFport: 9090\r\nhost: db" +``` + +Критерии раскрытия фиксированы: многострочная замена, рост сверх `max(100, исходная длина строки)` либо не менее четырёх экранирований с накладными расходами от 25% для отдельной строки замены. Ширина считается в Unicode scalar values, а не байтах UTF-8 или колонках терминала. Уже длинная строка без роста сохраняется. Новые уровни используют четыре пробела и EOL исходника. Если CR или строка данных `))` мешают lossless-кодированию вне inline, сохраняется корректный inline-вариант; эти символы не означают автоматический отказ любой inline-правки. + +#### 8. Точная замена Integer + +Домен Integer в исходнике — знаковый 64-битный. Это значение больше безопасного диапазона JavaScript Number, но помещается в i64; используйте точное host-представление, а не округлённое число с плавающей точкой. Типизированный Integer вне i64 невозможно сохранить в исходнике как Integer: правка отказывает, не обрезая значение. Для текстового большого идентификатора используйте String. Float различает отрицательный и положительный нуль; no-op для Object не зависит от порядка ключей, порядок Array значим. + +```python +updated = ktav.edit_value("n: 1\n", "n", 9007199254740993) +``` + +```ktav +n: 9007199254740993 +``` + +### Диагностика и безопасные отказы в 0.9 + +Координаты исходника — байтовые смещения UTF-8 с учётом BOM; spans полуоткрыты `[start, end)`, строки нумеруются с 1. Поддерживаются LF, отдельный CR и CRLF; CRLF считается одним переводом строки. Один Unicode-символ может занимать несколько байтов. + +Незавершённый `a: [\n` даёт `UnclosedCompound`, строку 1 и span `3..5`: начало — самая внутренняя незакрытая скобка, а не начало ключа или строки. Для сырых байтов `61 3A 20 FF` (`a: ` и невалидный UTF-8) валидация сообщает `InvalidUtf8`, строку 1 и покрывающий span `3..4`; `line_text` равен null, а не придуманному тексту после lossy-декодирования. Проверка UTF-8 предшествует грамматике. + +Некорректный текстовый путь, включая пустой путь или пустой текстовый сегмент, даёт `EditInvalidPath`; смещение считается в байтах UTF-8 самого пути. Пустой список сегментов, отсутствующий ключ, индекс вне диапазона или спуск через скаляр дают `EditNotFound`. В объекте числовой сегмент остаётся ключом; индекс массива содержит ASCII-цифры, допускает ведущие нули, но не знаки. + +Целые промежуточные объекты из dotted/reopened-определений могут занимать несколько физических диапазонов и давать `EditUnsupported`; их существующие листья остаются редактируемыми. Структурная замена контейнера не должна удалять внутренние комментарии. Ошибка не возвращает частичный патч и не меняет переданный исходник. Результат повторно разбирается и семантически проверяется: цель должна равняться замене, остальное дерево значений — исходному. + +В привязках ошибочный исходник даёт обычный конверт парсера до проверки пути. Некорректный wire-payload — ошибка `Message` без выдуманных координат. Wire-конверт содержит `error`, `reason`, `line`, `line_text`, `span`, `path`, `body`, `canonical`, `spec_section`, `message`; имена host-accessors описаны в разделе ошибок. В `body` находятся десятичное байтовое смещение пути для `EditInvalidPath`, null для `EditNotFound` и причина отказа для `EditUnsupported`. + В отличие от биндингов для JavaScript, `canonical_from_source` не даёт здесь дополнительной численной точности: Python различает `int` и `float`, поэтому различие Integer/Float из Ktav переживает `loads`, и diff --git a/docs/zh/CHANGELOG.zh.md b/docs/zh/CHANGELOG.zh.md index c1d57a4..c704bbd 100644 --- a/docs/zh/CHANGELOG.zh.md +++ b/docs/zh/CHANGELOG.zh.md @@ -11,6 +11,30 @@ MINOR 版本升级视为破坏性。 [`ktav-lang/spec`](https://github.com/ktav-lang/spec)。底层 Rust 实现见 [`ktav-lang/rust`](https://github.com/ktav-lang/rust)。 +## 尚未发布 — 0.9 准备版本 + +- `ktav.edit_value(source, path, replacement)` 与 + `ktav.edit_value_segments(source, segments, replacement)` —— + 无损的原地源文本编辑(source-edit 0.9)。只有目标值的字节会改变 + (加上布局规则要求展开的 inline 包装层);注释、键拼写、空行、 + BOM 与 CR/LF/CRLF 全部保留,相同替换是字节级 no-op。新增异常家族 + `KtavEditError`,含 `KtavInvalidPathError`(`body` = 路径参数的 + UTF-8 字节偏移十进制串)、`KtavNotFoundError` 与 + `KtavUnsupportedError`;信封仍是同样的十字段,`error` 取 + `EditInvalidPath` / `EditNotFound` / `EditUnsupported` 之一。 +- spec 0.9 语料:conformance 运行器现在执行 `versions/0.9/tests` + 的 fixture(162 个 invalid —— 其中 72 个是新的 `diagnostics09` + EOF/坏 UTF-8 诊断),校验 `expected_location` 元数据(line、 + 原始字节 `start`、精确 `end` 或 `minimum_end`),并让所有 + `raw_bytes` fixture 走共享的字节边界,因此两个 backend 中坏 + UTF-8 都会抛出结构化的 `InvalidUtf8` 信封。 +- `UnclosedCompound` 错误现在固定 opener:`line` 与 `line_text` + 指向打开最内层未闭合容器的行,`span` 从该 opener 延伸到输入末尾。 + +### 文档 + +- 扩展 README 示例:点分路径与字面键、混合数组、String/Integer 区别、多行展开、逐字节 no-op 及 BOM/CRLF/EOF 保留。明确 0.9 字节诊断、安全拒绝、ABI 2 和独立纯实现用法;这些新增功能不属于已发布的 0.8.1。 + ## [0.8.1] 与 Ktav 规范 0.8.1 和 Rust core 0.8.1 同步。本版本的主要新内容:完整的 @@ -54,24 +78,6 @@ Rust 实现见 [`ktav-lang/rust`](https://github.com/ktav-lang/rust)。 它的安装不需要 Rust 工具链、编译器或 maturin,并且只提供 `ktav.pure` 这一个 backend。 -- `ktav.edit_value(source, path, replacement)` 与 - `ktav.edit_value_segments(source, segments, replacement)` —— - 无损的原地源文本编辑(source-edit 0.9)。只有目标值的字节会改变 - (加上布局规则要求展开的 inline 包装层);注释、键拼写、空行、 - BOM 与 CR/LF/CRLF 全部保留,相同替换是字节级 no-op。新增异常家族 - `KtavEditError`,含 `KtavInvalidPathError`(`body` = 路径参数的 - UTF-8 字节偏移十进制串)、`KtavNotFoundError` 与 - `KtavUnsupportedError`;信封仍是同样的十字段,`error` 取 - `EditInvalidPath` / `EditNotFound` / `EditUnsupported` 之一。 -- spec 0.9 语料:conformance 运行器现在执行 `versions/0.9/tests` - 的 fixture(162 个 invalid —— 其中 72 个是新的 `diagnostics09` - EOF/坏 UTF-8 诊断),校验 `expected_location` 元数据(line、 - 原始字节 `start`、精确 `end` 或 `minimum_end`),并让所有 - `raw_bytes` fixture 走共享的字节边界,因此两个 backend 中坏 - UTF-8 都会抛出结构化的 `InvalidUtf8` 信封。 -- `UnclosedCompound` 错误现在固定 opener:`line` 与 `line_text` - 指向打开最内层未闭合容器的行,`span` 从该 opener 延伸到输入末尾。 - ### Changed - 升级到 Rust core 0.8.1 与 spec 0.8.1(发布为规范仓库的 diff --git a/docs/zh/README.zh.md b/docs/zh/README.zh.md index f37863d..1312797 100644 --- a/docs/zh/README.zh.md +++ b/docs/zh/README.zh.md @@ -196,11 +196,162 @@ parse→mutate→serialize:有效修改之外的注释、键拼写、顺序、 BOM 与 CR/LF/CRLF 按字节保留,dotted/inline/block 形式得以维持, 相同替换是字节级 no-op —— 即使拼写非规范。每个成功的补丁都会 重新解析并做语义校验。当不存在无损补丁时(noncontiguous 的 -dotted/reopen 目标、结构替换下的内部注释、multiline 替换中的 -`))` 行),调用抛出 `KtavUnsupportedError` 而不是猜测。长或多行 +dotted/reopen 目标、结构替换下的内部注释、或在目标上下文中无法 +无损表示的值),调用抛出 `KtavUnsupportedError` 而不是猜测。长或多行 替换只展开被触及的 inline 包装层;未触及的嵌套分支保持 inline。 native 与 pure backend 实现完全一致的语义。 +### 源文本编辑示例 + +以下示例适用于尚未发布的 0.9 API,而非已发布的 0.8.1 包。只能替换已有值:不会重命名键、创建缺失路径或删除条目。各代码片段相互独立;Rust 的 `?` 假定外层函数返回 `Result`。Go 示例仅针对固定且有效的输入使用 panic;应用程序应处理返回的错误。 + +绑定示例使用无需原生二进制的独立纯实现。原生入口接收相同的路径和值:Go 的 `ktav.EditValue`、Java 的 `Ktav.editValue`、C# 的 `KtavApi.EditValue(..., KtavBackend.Native)`、PHP 的 `Ktav::editValue`、JS 包的 native/FFI 导出及 Python 的 `ktav.edit_value`。C ABI 后端要求 ABI 2;PyO3/N-API/WASM 要求兼容的 0.9 准备核心。Bun/Deno FFI 返回 promise,需要 `await`;此处 pure/Node/WASM 示例为同步调用。 + +```python +import ktav.pure as ktav +``` + +#### 1. 通过点分键修改部署配置 + +只修改地址;注释、点分形式及相邻的用户字段逐字节保持不变。 + +```python +source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n" +updated = ktav.edit_value(source, "targets.storagehost.address", "192.168.0.88:22") +``` + +结果: + +```ktav +## deployment +targets.storagehost.address: 192.168.0.88:22 +targets.storagehost.user: mcp-agent +``` + +#### 2. 字面点号:文本路径或路径段 + +源码中带引号的键名就是 `a.b`。文本路径需要转义点号;路径段 API 直接接收解码后的键名。两个调用返回相同结果。 + +```python +source = "\"a.b\": {port: 80}\n" +updated = ktav.edit_value(source, "a\\.b.port", 90) +same = ktav.edit_value_segments(source, ["a.b", "port"], 90) +``` + +结果: + +```ktav +"a.b": {port: 90} +``` + +#### 3. 修改混合形式数组中的叶子值 + +此处 `0` 是数组索引;在对象中,同一个路径段表示名称为 `0` 的键。未修改的容器保持行内形式。 + +```python +source = "servers: [{host: old, keep: yes}, standby]\n" +updated = ktav.edit_value_segments(source, ["servers", "0", "host"], "new") +``` + +结果: + +```ktav +servers: [{host: new, keep: yes}, standby] +``` + +#### 4. 看似数字的字符串仍然是字符串 + +替换值是 String,而不是 Integer。raw 标记保留这种区别;需要数值时请传入类型化 Integer。 + +```python +source = "port: 8080\n" +updated = ktav.edit_value(source, "port", "9090") +``` + +结果: + +```ktav +port:: 9090 +``` + +#### 5. 多行替换:仅展开必要的容器 + +修改的数组以四空格缩进展开。未修改的对象保持行内形式,verbatim 字符串内容不会重新缩进。 + +```python +source = "a: [old, {keep: yes}]\n" +updated = ktav.edit_value(source, "a.0", "x\ny") +``` + +结果: + +```ktav +a: [ + (( +x +y + )) + {keep: yes} +] +``` + +#### 6. 无变化时保留非规范拼写 + +Integer 的值已经是 1。相等判断直接返回原始字节,包括 `+1` 及分隔符周围的空白,不应用可读性阈值。 + +```python +source = "n : +1\n" +updated = ktav.edit_value(source, "n", 1) +assert updated == source +``` + +结果: + +```ktav +n : +1 +``` + +#### 7. BOM、CRLF 及无换行符的末行 + +返回值保留 BOM 和 CRLF,且不会增加末尾换行。以下转义表示使这些字节清晰可见。 + +```python +source = "\ufeffport: 8080\r\nhost: db" +updated = ktav.edit_value(source, "port", 9090) +``` + +结果: + +```text +"\uFEFFport: 9090\r\nhost: db" +``` + +展开条件固定:替换中包含多行字符串、修改后行长增长并超过 `max(100, 原始行长)`,或单个替换字符串需要至少四个转义且编码开销达到 25%。宽度按 Unicode 标量值计算,而非 UTF-8 字节或终端列。原本已很长但没有增长的行保持不变。新层级使用四空格及源文本的 EOL。若 CR 或数据行 `))` 无法无损转换为独立行,则保留有效的行内候选;这些字符不会使所有行内编辑自动失败。 + +#### 8. 精确替换 Integer + +源文本的 Integer 域是有符号 64 位。此值超过 JavaScript Number 的安全整数范围,但仍在 i64 内;应使用精确的宿主表示,而非已舍入的浮点值。超出 i64 的类型化 Integer 无法在源码中保持 Integer 身份,因此会被拒绝而不是截断。大型文本标识符应使用 String。Float 区分负零和正零;Object 的 no-op 相等忽略键顺序,而 Array 顺序仍然重要。 + +```python +updated = ktav.edit_value("n: 1\n", "n", 9007199254740993) +``` + +```ktav +n: 9007199254740993 +``` + +### 0.9 的诊断与安全失败 + +源码坐标为包含 BOM 的 UTF-8 字节偏移,span 使用半开区间 `[start, end)`,行号从 1 开始。支持 LF、独立 CR 和 CRLF,且 CRLF 计为一个换行。一个 Unicode 字符可能占用多个字节。 + +未完成的 `a: [\n` 报告 `UnclosedCompound`、第 1 行和 span `3..5`:区间从最内层未闭合的起始括号开始,而非键或行的开头。原始字节 `61 3A 20 FF`(`a: ` 后接无效 UTF-8)报告 `InvalidUtf8`、第 1 行及覆盖区间 `3..4`;`line_text` 为 null,不会通过有损解码伪造文本。UTF-8 校验优先于语法处理。 + +非法文本路径(包括空路径或空文本段)报告 `EditInvalidPath`,偏移按路径本身的 UTF-8 字节计算。空路径段列表、缺失键、索引越界或穿过标量下钻报告 `EditNotFound`。对象中的数字段仍是键;数组索引仅接受 ASCII 数字,允许前导零,不允许正负号。 + +由 dotted/reopened 定义拼成的整个中间对象可能占据多个物理范围,因此报告 `EditUnsupported`;已有叶子值仍可修改。容器结构替换不能删除内部注释。失败调用不会返回部分补丁,也不会修改传入的源码。返回文本会重新解析并进行语义检查:目标必须等于替换值,其余值树必须与原文相等。 + +在绑定中,无效源码会先于路径验证报告普通解析错误信封。非法 wire 载荷是无虚构源码坐标的 `Message` 错误。wire 信封包含 `error`、`reason`、`line`、`line_text`、`span`、`path`、`body`、`canonical`、`spec_section`、`message`;宿主语言的访问器名称见错误章节。`body` 分别承载 `EditInvalidPath` 的十进制路径字节偏移、`EditNotFound` 的 null,以及 `EditUnsupported` 的拒绝原因。 + 与 JavaScript 绑定不同,`canonical_from_source` 在这里不会带来额外的 数值精度 —— Python 区分 `int` 与 `float`,因此 Ktav 的 Integer/Float 之分在 `loads` 之后依然保留,并且 `emit_canonical(loads(src))` 产生的 diff --git a/root-docs/CHANGELOG/manifest.js b/root-docs/CHANGELOG/manifest.js index 3ef2f46..89c8caa 100644 --- a/root-docs/CHANGELOG/manifest.js +++ b/root-docs/CHANGELOG/manifest.js @@ -1,5 +1,6 @@ export default [ "intro", + "source-edit09", "unreleased", "unreleased-added", "unreleased-changed", diff --git a/root-docs/CHANGELOG/unreleased-added/body-3.md b/root-docs/CHANGELOG/source-edit09/body-1.md similarity index 76% rename from root-docs/CHANGELOG/unreleased-added/body-3.md rename to root-docs/CHANGELOG/source-edit09/body-1.md index f92b7ce..5199dfa 100644 --- a/root-docs/CHANGELOG/unreleased-added/body-3.md +++ b/root-docs/CHANGELOG/source-edit09/body-1.md @@ -1,4 +1,6 @@ >>>>> lang=en +## Unreleased — 0.9 preparation + - `ktav.edit_value(source, path, replacement)` and `ktav.edit_value_segments(source, segments, replacement)` — lossless in-place source edits (source-edit 0.9). Only the bytes of the target @@ -20,7 +22,13 @@ name the line that opened the innermost unclosed compound, and `span` runs from that opener to end of input. +### Documentation + +- Expand README examples for dotted and literal-key paths, mixed arrays, String/Integer identity, multiline unfolding, byte-identical no-op and BOM/CRLF/EOF preservation. Clarify 0.9 byte diagnostics, safe refusal, ABI 2 and standalone pure usage; these additions are not part of published 0.8.1. + >>>>> lang=ru +## Ещё не выпущено — подготовка 0.9 + - `ktav.edit_value(source, path, replacement)` и `ktav.edit_value_segments(source, segments, replacement)` — lossless-правка исходника по месту (source-edit 0.9). Меняются только @@ -43,7 +51,13 @@ `line_text` называют строку, открывшую ближайший незакрытый контейнер, а `span` тянется от него до конца ввода. +### Документация + +- Дополнены примеры README: dotted-пути и буквальные ключи, смешанные массивы, различие String/Integer, раскрытие многострочной замены, побайтовый no-op и сохранение BOM/CRLF/EOF. Уточнены байтовая диагностика 0.9, безопасные отказы, ABI 2 и самостоятельный pure-бэкенд; дополнения не относятся к опубликованному 0.8.1. + >>>>> lang=zh +## 尚未发布 — 0.9 准备版本 + - `ktav.edit_value(source, path, replacement)` 与 `ktav.edit_value_segments(source, segments, replacement)` —— 无损的原地源文本编辑(source-edit 0.9)。只有目标值的字节会改变 @@ -62,3 +76,7 @@ - `UnclosedCompound` 错误现在固定 opener:`line` 与 `line_text` 指向打开最内层未闭合容器的行,`span` 从该 opener 延伸到输入末尾。 +### 文档 + +- 扩展 README 示例:点分路径与字面键、混合数组、String/Integer 区别、多行展开、逐字节 no-op 及 BOM/CRLF/EOF 保留。明确 0.9 字节诊断、安全拒绝、ABI 2 和独立纯实现用法;这些新增功能不属于已发布的 0.8.1。 + diff --git a/root-docs/CHANGELOG/source-edit09/meta.js b/root-docs/CHANGELOG/source-edit09/meta.js new file mode 100644 index 0000000..eb86416 --- /dev/null +++ b/root-docs/CHANGELOG/source-edit09/meta.js @@ -0,0 +1,7 @@ +export default { + "kind": "frontmatter", + "number": null, + "level": null, + "title": null, + "bodyParts": 1 +} diff --git a/root-docs/CHANGELOG/unreleased-added/meta.js b/root-docs/CHANGELOG/unreleased-added/meta.js index 6f4ff20..7e0a98b 100644 --- a/root-docs/CHANGELOG/unreleased-added/meta.js +++ b/root-docs/CHANGELOG/unreleased-added/meta.js @@ -3,5 +3,5 @@ export default { "number": null, "level": null, "title": null, - "bodyParts": 3 + "bodyParts": 2 } diff --git a/root-docs/README/diagnostics09/body-1.md b/root-docs/README/diagnostics09/body-1.md new file mode 100644 index 0000000..7484af6 --- /dev/null +++ b/root-docs/README/diagnostics09/body-1.md @@ -0,0 +1,39 @@ +>>>>> lang=en +### 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. + +An unfinished `a: [\n` reports `UnclosedCompound`, line 1 and span `3..5`: the span begins at the innermost unmatched opener, not the start of its key or line. For raw bytes `61 3A 20 FF` (`a: ` followed by invalid UTF-8), validation reports `InvalidUtf8`, line 1 and a covering span `3..4`; `line_text` is null rather than fabricated by lossy decoding. UTF-8 validation precedes grammar processing. + +A malformed textual path, including an empty textual path or empty textual segment, is `EditInvalidPath`; its offset is measured in the path's UTF-8 bytes. An empty segments list, missing key, out-of-range index or scalar descent is `EditNotFound`. Object numeric segments remain keys; array indexes use ASCII digits, allow leading zeros and reject signs. + +Whole dotted/reopened intermediate objects may occupy several physical ranges and are `EditUnsupported`; their existing leaves can still be edited. Replacing a container must not discard interior comments. No failed call returns a partial patch or changes the supplied source. The returned text is re-parsed and semantically checked: the target must equal the replacement and the rest of the value tree must remain equal. + +For bindings, invalid source is reported with the ordinary parser envelope before path validation. Malformed wire payloads are `Message` errors without invented source coordinates. The wire envelope has `error`, `reason`, `line`, `line_text`, `span`, `path`, `body`, `canonical`, `spec_section` and `message`; host accessor names are documented in the errors section. `body` carries the decimal path-byte offset for `EditInvalidPath`, null for `EditNotFound`, and the refusal reason for `EditUnsupported`. + +>>>>> lang=ru +### Диагностика и безопасные отказы в 0.9 + +Координаты исходника — байтовые смещения UTF-8 с учётом BOM; spans полуоткрыты `[start, end)`, строки нумеруются с 1. Поддерживаются LF, отдельный CR и CRLF; CRLF считается одним переводом строки. Один Unicode-символ может занимать несколько байтов. + +Незавершённый `a: [\n` даёт `UnclosedCompound`, строку 1 и span `3..5`: начало — самая внутренняя незакрытая скобка, а не начало ключа или строки. Для сырых байтов `61 3A 20 FF` (`a: ` и невалидный UTF-8) валидация сообщает `InvalidUtf8`, строку 1 и покрывающий span `3..4`; `line_text` равен null, а не придуманному тексту после lossy-декодирования. Проверка UTF-8 предшествует грамматике. + +Некорректный текстовый путь, включая пустой путь или пустой текстовый сегмент, даёт `EditInvalidPath`; смещение считается в байтах UTF-8 самого пути. Пустой список сегментов, отсутствующий ключ, индекс вне диапазона или спуск через скаляр дают `EditNotFound`. В объекте числовой сегмент остаётся ключом; индекс массива содержит ASCII-цифры, допускает ведущие нули, но не знаки. + +Целые промежуточные объекты из dotted/reopened-определений могут занимать несколько физических диапазонов и давать `EditUnsupported`; их существующие листья остаются редактируемыми. Структурная замена контейнера не должна удалять внутренние комментарии. Ошибка не возвращает частичный патч и не меняет переданный исходник. Результат повторно разбирается и семантически проверяется: цель должна равняться замене, остальное дерево значений — исходному. + +В привязках ошибочный исходник даёт обычный конверт парсера до проверки пути. Некорректный wire-payload — ошибка `Message` без выдуманных координат. Wire-конверт содержит `error`, `reason`, `line`, `line_text`, `span`, `path`, `body`, `canonical`, `spec_section`, `message`; имена host-accessors описаны в разделе ошибок. В `body` находятся десятичное байтовое смещение пути для `EditInvalidPath`, null для `EditNotFound` и причина отказа для `EditUnsupported`. + +>>>>> lang=zh +### 0.9 的诊断与安全失败 + +源码坐标为包含 BOM 的 UTF-8 字节偏移,span 使用半开区间 `[start, end)`,行号从 1 开始。支持 LF、独立 CR 和 CRLF,且 CRLF 计为一个换行。一个 Unicode 字符可能占用多个字节。 + +未完成的 `a: [\n` 报告 `UnclosedCompound`、第 1 行和 span `3..5`:区间从最内层未闭合的起始括号开始,而非键或行的开头。原始字节 `61 3A 20 FF`(`a: ` 后接无效 UTF-8)报告 `InvalidUtf8`、第 1 行及覆盖区间 `3..4`;`line_text` 为 null,不会通过有损解码伪造文本。UTF-8 校验优先于语法处理。 + +非法文本路径(包括空路径或空文本段)报告 `EditInvalidPath`,偏移按路径本身的 UTF-8 字节计算。空路径段列表、缺失键、索引越界或穿过标量下钻报告 `EditNotFound`。对象中的数字段仍是键;数组索引仅接受 ASCII 数字,允许前导零,不允许正负号。 + +由 dotted/reopened 定义拼成的整个中间对象可能占据多个物理范围,因此报告 `EditUnsupported`;已有叶子值仍可修改。容器结构替换不能删除内部注释。失败调用不会返回部分补丁,也不会修改传入的源码。返回文本会重新解析并进行语义检查:目标必须等于替换值,其余值树必须与原文相等。 + +在绑定中,无效源码会先于路径验证报告普通解析错误信封。非法 wire 载荷是无虚构源码坐标的 `Message` 错误。wire 信封包含 `error`、`reason`、`line`、`line_text`、`span`、`path`、`body`、`canonical`、`spec_section`、`message`;宿主语言的访问器名称见错误章节。`body` 分别承载 `EditInvalidPath` 的十进制路径字节偏移、`EditNotFound` 的 null,以及 `EditUnsupported` 的拒绝原因。 + diff --git a/root-docs/README/diagnostics09/meta.js b/root-docs/README/diagnostics09/meta.js new file mode 100644 index 0000000..eb86416 --- /dev/null +++ b/root-docs/README/diagnostics09/meta.js @@ -0,0 +1,7 @@ +export default { + "kind": "frontmatter", + "number": null, + "level": null, + "title": null, + "bodyParts": 1 +} diff --git a/root-docs/README/editing-cookbook/body-1.md b/root-docs/README/editing-cookbook/body-1.md new file mode 100644 index 0000000..24d16c4 --- /dev/null +++ b/root-docs/README/editing-cookbook/body-1.md @@ -0,0 +1,84 @@ +>>>>> lang=en +### 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. + +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. + +```python +import ktav.pure as ktav +``` + +#### 1. Dotted deployment settings + +Only the address changes; the comment, dotted form and neighbouring user entry remain byte-for-byte unchanged. + +```python +source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n" +updated = ktav.edit_value(source, "targets.storagehost.address", "192.168.0.88:22") +``` + +Result: + +```ktav +## deployment +targets.storagehost.address: 192.168.0.88:22 +targets.storagehost.user: mcp-agent +``` + +>>>>> lang=ru +### Практические примеры правки исходника + +Примеры относятся к ещё не выпущенному 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-варианты синхронны. + +```python +import ktav.pure as ktav +``` + +#### 1. Настройка развёртывания через dotted-ключ + +Меняется только адрес; комментарий, dotted-форма и соседнее поле пользователя сохраняются байт-в-байт. + +```python +source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n" +updated = ktav.edit_value(source, "targets.storagehost.address", "192.168.0.88:22") +``` + +Результат: + +```ktav +## deployment +targets.storagehost.address: 192.168.0.88:22 +targets.storagehost.user: mcp-agent +``` + +>>>>> lang=zh +### 源文本编辑示例 + +以下示例适用于尚未发布的 0.9 API,而非已发布的 0.8.1 包。只能替换已有值:不会重命名键、创建缺失路径或删除条目。各代码片段相互独立;Rust 的 `?` 假定外层函数返回 `Result`。Go 示例仅针对固定且有效的输入使用 panic;应用程序应处理返回的错误。 + +绑定示例使用无需原生二进制的独立纯实现。原生入口接收相同的路径和值:Go 的 `ktav.EditValue`、Java 的 `Ktav.editValue`、C# 的 `KtavApi.EditValue(..., KtavBackend.Native)`、PHP 的 `Ktav::editValue`、JS 包的 native/FFI 导出及 Python 的 `ktav.edit_value`。C ABI 后端要求 ABI 2;PyO3/N-API/WASM 要求兼容的 0.9 准备核心。Bun/Deno FFI 返回 promise,需要 `await`;此处 pure/Node/WASM 示例为同步调用。 + +```python +import ktav.pure as ktav +``` + +#### 1. 通过点分键修改部署配置 + +只修改地址;注释、点分形式及相邻的用户字段逐字节保持不变。 + +```python +source = "## deployment\ntargets.storagehost.address: old\ntargets.storagehost.user: mcp-agent\n" +updated = ktav.edit_value(source, "targets.storagehost.address", "192.168.0.88:22") +``` + +结果: + +```ktav +## deployment +targets.storagehost.address: 192.168.0.88:22 +targets.storagehost.user: mcp-agent +``` + diff --git a/root-docs/README/editing-cookbook/body-2.md b/root-docs/README/editing-cookbook/body-2.md new file mode 100644 index 0000000..63c9472 --- /dev/null +++ b/root-docs/README/editing-cookbook/body-2.md @@ -0,0 +1,84 @@ +>>>>> lang=en +#### 2. Literal dots: textual path or segments + +The quoted source key is literally `a.b`. The textual path escapes its dot; the segments call passes the decoded key directly. Both calls return the same result. + +```python +source = "\"a.b\": {port: 80}\n" +updated = ktav.edit_value(source, "a\\.b.port", 90) +same = ktav.edit_value_segments(source, ["a.b", "port"], 90) +``` + +Result: + +```ktav +"a.b": {port: 90} +``` + +#### 3. A leaf inside a mixed-form array + +`0` is an array index here. Inside an Object, the same segment would address the key named `0`; untouched containers remain inline. + +```python +source = "servers: [{host: old, keep: yes}, standby]\n" +updated = ktav.edit_value_segments(source, ["servers", "0", "host"], "new") +``` + +Result: + +>>>>> lang=ru +#### 2. Буквальные точки: текстовый путь или сегменты + +Ключ исходника в кавычках буквально называется `a.b`. В текстовом пути точка экранируется; API сегментов получает декодированное имя напрямую. Оба вызова возвращают одинаковый результат. + +```python +source = "\"a.b\": {port: 80}\n" +updated = ktav.edit_value(source, "a\\.b.port", 90) +same = ktav.edit_value_segments(source, ["a.b", "port"], 90) +``` + +Результат: + +```ktav +"a.b": {port: 90} +``` + +#### 3. Лист внутри массива со смешанными формами + +Здесь `0` — индекс массива. В объекте такой же сегмент обозначал бы ключ с именем `0`; нетронутые контейнеры остаются inline. + +```python +source = "servers: [{host: old, keep: yes}, standby]\n" +updated = ktav.edit_value_segments(source, ["servers", "0", "host"], "new") +``` + +Результат: + +>>>>> lang=zh +#### 2. 字面点号:文本路径或路径段 + +源码中带引号的键名就是 `a.b`。文本路径需要转义点号;路径段 API 直接接收解码后的键名。两个调用返回相同结果。 + +```python +source = "\"a.b\": {port: 80}\n" +updated = ktav.edit_value(source, "a\\.b.port", 90) +same = ktav.edit_value_segments(source, ["a.b", "port"], 90) +``` + +结果: + +```ktav +"a.b": {port: 90} +``` + +#### 3. 修改混合形式数组中的叶子值 + +此处 `0` 是数组索引;在对象中,同一个路径段表示名称为 `0` 的键。未修改的容器保持行内形式。 + +```python +source = "servers: [{host: old, keep: yes}, standby]\n" +updated = ktav.edit_value_segments(source, ["servers", "0", "host"], "new") +``` + +结果: + diff --git a/root-docs/README/editing-cookbook/body-3.md b/root-docs/README/editing-cookbook/body-3.md new file mode 100644 index 0000000..bd375c9 --- /dev/null +++ b/root-docs/README/editing-cookbook/body-3.md @@ -0,0 +1,93 @@ +>>>>> lang=en +```ktav +servers: [{host: new, keep: yes}, standby] +``` + +#### 4. A numeric-looking String stays a String + +The replacement is a String, not an Integer. The raw marker preserves that distinction. Supply a typed Integer when a numeric value is intended. + +```python +source = "port: 8080\n" +updated = ktav.edit_value(source, "port", "9090") +``` + +Result: + +```ktav +port:: 9090 +``` + +#### 5. Multiline replacement: expand only what is necessary + +The changed array expands with four-space indentation. The untouched object stays inline, and verbatim string contents are not reindented. + +```python +source = "a: [old, {keep: yes}]\n" +updated = ktav.edit_value(source, "a.0", "x\ny") +``` + +Result: + +>>>>> lang=ru +```ktav +servers: [{host: new, keep: yes}, standby] +``` + +#### 4. Похожая на число строка остаётся строкой + +Замена имеет тип String, а не Integer. Raw-маркер сохраняет это различие. Для числового значения передавайте типизированный Integer. + +```python +source = "port: 8080\n" +updated = ktav.edit_value(source, "port", "9090") +``` + +Результат: + +```ktav +port:: 9090 +``` + +#### 5. Многострочная замена: раскрывается только необходимое + +Изменённый массив раскрывается с отступом четыре пробела. Нетронутый объект остаётся inline, содержимое verbatim-строки не переотступается. + +```python +source = "a: [old, {keep: yes}]\n" +updated = ktav.edit_value(source, "a.0", "x\ny") +``` + +Результат: + +>>>>> lang=zh +```ktav +servers: [{host: new, keep: yes}, standby] +``` + +#### 4. 看似数字的字符串仍然是字符串 + +替换值是 String,而不是 Integer。raw 标记保留这种区别;需要数值时请传入类型化 Integer。 + +```python +source = "port: 8080\n" +updated = ktav.edit_value(source, "port", "9090") +``` + +结果: + +```ktav +port:: 9090 +``` + +#### 5. 多行替换:仅展开必要的容器 + +修改的数组以四空格缩进展开。未修改的对象保持行内形式,verbatim 字符串内容不会重新缩进。 + +```python +source = "a: [old, {keep: yes}]\n" +updated = ktav.edit_value(source, "a.0", "x\ny") +``` + +结果: + diff --git a/root-docs/README/editing-cookbook/body-4.md b/root-docs/README/editing-cookbook/body-4.md new file mode 100644 index 0000000..3b7af59 --- /dev/null +++ b/root-docs/README/editing-cookbook/body-4.md @@ -0,0 +1,87 @@ +>>>>> lang=en +```ktav +a: [ + (( +x +y + )) + {keep: yes} +] +``` + +#### 6. No-op preserves noncanonical spelling + +The Integer value is already 1. Equality returns the original bytes, including `+1` and the original separator spacing; readability thresholds are bypassed. + +```python +source = "n : +1\n" +updated = ktav.edit_value(source, "n", 1) +assert updated == source +``` + +Result: + +```ktav +n : +1 +``` + +#### 7. BOM, CRLF and an unterminated final line + +>>>>> lang=ru +```ktav +a: [ + (( +x +y + )) + {keep: yes} +] +``` + +#### 6. No-op сохраняет неканоническое написание + +Значение Integer уже равно 1. Проверка равенства возвращает исходные байты, включая `+1` и пробелы разделителя; критерии читаемости не применяются. + +```python +source = "n : +1\n" +updated = ktav.edit_value(source, "n", 1) +assert updated == source +``` + +Результат: + +```ktav +n : +1 +``` + +#### 7. BOM, CRLF и последняя строка без перевода + +>>>>> lang=zh +```ktav +a: [ + (( +x +y + )) + {keep: yes} +] +``` + +#### 6. 无变化时保留非规范拼写 + +Integer 的值已经是 1。相等判断直接返回原始字节,包括 `+1` 及分隔符周围的空白,不应用可读性阈值。 + +```python +source = "n : +1\n" +updated = ktav.edit_value(source, "n", 1) +assert updated == source +``` + +结果: + +```ktav +n : +1 +``` + +#### 7. BOM、CRLF 及无换行符的末行 + diff --git a/root-docs/README/editing-cookbook/body-5.md b/root-docs/README/editing-cookbook/body-5.md new file mode 100644 index 0000000..f58f11c --- /dev/null +++ b/root-docs/README/editing-cookbook/body-5.md @@ -0,0 +1,84 @@ +>>>>> lang=en +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. + +```python +source = "\ufeffport: 8080\r\nhost: db" +updated = ktav.edit_value(source, "port", 9090) +``` + +Result: + +```text +"\uFEFFport: 9090\r\nhost: db" +``` + +Expansion is deterministic: a multiline replacement, growth beyond `max(100, original line length)`, or at least four escapes with at least 25% encoding overhead for an individual replacement string. Width counts Unicode scalar values, not UTF-8 bytes or terminal columns. An already-long line without growth is kept. New levels use four spaces and the source EOL. If CR or a `))` data line prevents lossless standalone encoding, a valid inline candidate is retained; these characters do not automatically make every inline edit unsupported. + +#### 8. Exact Integer replacement + +The source Integer domain is signed 64-bit. This value exceeds JavaScript's safe-Number range but fits i64; use an exact host representation, not a rounded floating-point value. A typed Integer outside i64 cannot be preserved as an Integer in source and is refused instead of truncated. Use a String when a large identifier is text. Float identity distinguishes negative and positive zero; Object no-op equality ignores key order, while Array order remains significant. + +```python +updated = ktav.edit_value("n: 1\n", "n", 9007199254740993) +``` + +```ktav +n: 9007199254740993 +``` + +>>>>> lang=ru +Результат сохраняет BOM и CRLF, не добавляя финальный перевод строки. Экранированное представление делает эти байты видимыми. + +```python +source = "\ufeffport: 8080\r\nhost: db" +updated = ktav.edit_value(source, "port", 9090) +``` + +Результат: + +```text +"\uFEFFport: 9090\r\nhost: db" +``` + +Критерии раскрытия фиксированы: многострочная замена, рост сверх `max(100, исходная длина строки)` либо не менее четырёх экранирований с накладными расходами от 25% для отдельной строки замены. Ширина считается в Unicode scalar values, а не байтах UTF-8 или колонках терминала. Уже длинная строка без роста сохраняется. Новые уровни используют четыре пробела и EOL исходника. Если CR или строка данных `))` мешают lossless-кодированию вне inline, сохраняется корректный inline-вариант; эти символы не означают автоматический отказ любой inline-правки. + +#### 8. Точная замена Integer + +Домен Integer в исходнике — знаковый 64-битный. Это значение больше безопасного диапазона JavaScript Number, но помещается в i64; используйте точное host-представление, а не округлённое число с плавающей точкой. Типизированный Integer вне i64 невозможно сохранить в исходнике как Integer: правка отказывает, не обрезая значение. Для текстового большого идентификатора используйте String. Float различает отрицательный и положительный нуль; no-op для Object не зависит от порядка ключей, порядок Array значим. + +```python +updated = ktav.edit_value("n: 1\n", "n", 9007199254740993) +``` + +```ktav +n: 9007199254740993 +``` + +>>>>> lang=zh +返回值保留 BOM 和 CRLF,且不会增加末尾换行。以下转义表示使这些字节清晰可见。 + +```python +source = "\ufeffport: 8080\r\nhost: db" +updated = ktav.edit_value(source, "port", 9090) +``` + +结果: + +```text +"\uFEFFport: 9090\r\nhost: db" +``` + +展开条件固定:替换中包含多行字符串、修改后行长增长并超过 `max(100, 原始行长)`,或单个替换字符串需要至少四个转义且编码开销达到 25%。宽度按 Unicode 标量值计算,而非 UTF-8 字节或终端列。原本已很长但没有增长的行保持不变。新层级使用四空格及源文本的 EOL。若 CR 或数据行 `))` 无法无损转换为独立行,则保留有效的行内候选;这些字符不会使所有行内编辑自动失败。 + +#### 8. 精确替换 Integer + +源文本的 Integer 域是有符号 64 位。此值超过 JavaScript Number 的安全整数范围,但仍在 i64 内;应使用精确的宿主表示,而非已舍入的浮点值。超出 i64 的类型化 Integer 无法在源码中保持 Integer 身份,因此会被拒绝而不是截断。大型文本标识符应使用 String。Float 区分负零和正零;Object 的 no-op 相等忽略键顺序,而 Array 顺序仍然重要。 + +```python +updated = ktav.edit_value("n: 1\n", "n", 9007199254740993) +``` + +```ktav +n: 9007199254740993 +``` + diff --git a/root-docs/README/editing-cookbook/meta.js b/root-docs/README/editing-cookbook/meta.js new file mode 100644 index 0000000..f763e8e --- /dev/null +++ b/root-docs/README/editing-cookbook/meta.js @@ -0,0 +1,7 @@ +export default { + "kind": "frontmatter", + "number": null, + "level": null, + "title": null, + "bodyParts": 5 +} diff --git a/root-docs/README/manifest.js b/root-docs/README/manifest.js index 4e729c2..58bd63c 100644 --- a/root-docs/README/manifest.js +++ b/root-docs/README/manifest.js @@ -7,6 +7,8 @@ export default [ "formatting", "source-edit-status", "source-edit", + "editing-cookbook", + "diagnostics09", "canonical-and-entry-points", "type-mapping", "key-escaping", diff --git a/root-docs/README/source-edit/body-1.md b/root-docs/README/source-edit/body-1.md index 702bcf1..d5f12a3 100644 --- a/root-docs/README/source-edit/body-1.md +++ b/root-docs/README/source-edit/body-1.md @@ -28,8 +28,8 @@ dotted/inline/block forms are kept, and an equal replacement is a byte-identical no-op — even for noncanonical spelling. Every successful patch is re-parsed and semantically verified. When no lossless patch exists (noncontiguous dotted/reopened targets, internal -comments under structural replacement, a `))` line inside a multiline -replacement) the call raises `KtavUnsupportedError` instead of +comments under structural replacement, an unrepresentable value in the +target context) the call raises `KtavUnsupportedError` instead of guessing. Long or multiline replacements unfold only the touched inline wrappers; untouched nested branches stay inline. Both the native and the pure backend implement the identical semantics. @@ -64,8 +64,8 @@ dotted/inline/block-формы держатся, а совпадающая за byte-identical no-op, даже при неканоничном написании. Каждый успешный патч перепарсится и семантически проверяется. Когда lossless патча не существует (noncontiguous dotted/reopen-цели, внутренние -комментарии при структурной замене, строка `))` внутри multiline -замены), вызов бросает `KtavUnsupportedError`, а не угадывает. Длинные +комментарии при структурной замене, непредставимое в контексте цели +значение), вызов бросает `KtavUnsupportedError`, а не угадывает. Длинные и многострочные замены раскрывают только затронутые inline-обёртки; нетронутые ветки остаются inline. Native и pure backend реализуют идентичную семантику. @@ -96,8 +96,8 @@ parse→mutate→serialize:有效修改之外的注释、键拼写、顺序、 BOM 与 CR/LF/CRLF 按字节保留,dotted/inline/block 形式得以维持, 相同替换是字节级 no-op —— 即使拼写非规范。每个成功的补丁都会 重新解析并做语义校验。当不存在无损补丁时(noncontiguous 的 -dotted/reopen 目标、结构替换下的内部注释、multiline 替换中的 -`))` 行),调用抛出 `KtavUnsupportedError` 而不是猜测。长或多行 +dotted/reopen 目标、结构替换下的内部注释、或在目标上下文中无法 +无损表示的值),调用抛出 `KtavUnsupportedError` 而不是猜测。长或多行 替换只展开被触及的 inline 包装层;未触及的嵌套分支保持 inline。 native 与 pure backend 实现完全一致的语义。