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
4 changes: 2 additions & 2 deletions .github/workflows/CI.yml
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ jobs:
- name: Install test tooling
run: python -m pip install --upgrade pip maturin pytest pytest-cov "tomli>=2.5.0; python_version < '3.11'"
# Lock + provenance check before the native build compiles anything.
# The core is an IMMUTABLE git pin (Cargo.toml rev 447a00bd...);
# The core is an IMMUTABLE git pin (Cargo.toml rev 8b6b45ff...);
# the verification step below FAILS CLOSED on rev/version drift —
# it never skips unconditionally.
- name: Generate Cargo.lock (no --locked)
Expand All @@ -127,7 +127,7 @@ jobs:
import re, sys
from pathlib import Path

PIN = "447a00bd012e8d3f347c7e1eb59c3f0d9a78332f"
PIN = "8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910"
toml = Path("Cargo.toml").read_text(encoding="utf-8")
m = re.search(r'rev\s*=\s*"([0-9a-f]{40})"', toml)
if m is None:
Expand Down
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,16 @@ underlying Rust implementation, see
byte offset into the path), `KtavNotFoundError`, and
`KtavUnsupportedError`; the same ten-field envelope, `error` is one
of `EditInvalidPath` / `EditNotFound` / `EditUnsupported`.
- `ktav.insert_value(source, path, value)` and
`ktav.insert_value_segments(source, segments, value)` add a new Object
member without overwriting an existing key. `ktav.remove_value(source, path)`
and `ktav.remove_value_segments(source, segments)` remove an existing
value (array elements shift; empty parent Objects remain).
- `ktav.rename_key(source, path, new_key)` and
`ktav.rename_key_segments(source, segments, new_key)` rename an Object
member in place; `new_key` is one literal key, not a dotted path.
All six APIs use lossless source splices, are available in native and
pure-Python backends, and reject unsupported structural cases explicitly.
- 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`
Expand Down
2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ crate-type = ["cdylib"]

[dependencies]
# Подготовка 0.9: immutable core pin с source-edit; пакет ещё не опубликован.
ktav = { git = "https://github.com/ktav-lang/rust", rev = "447a00bd012e8d3f347c7e1eb59c3f0d9a78332f" }
ktav = { git = "https://github.com/ktav-lang/rust", rev = "8b6b45ffbd9e50e1588e8ab6b1ae5d422bbe8910" }
pyo3 = { version = "0.28", features = ["abi3-py39", "extension-module", "indexmap", "generate-import-lib"] }
indexmap = "2"
rustc-hash = "2"
Expand Down
32 changes: 32 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,38 @@ 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.

### Structural source edits — insert, remove, rename

```python
inserted = ktav.insert_value(source, "service.timeout", 30)
removed = ktav.remove_value(inserted, "service.old")
renamed = ktav.rename_key(removed, "service.timeout", "deadline")

# Literal segments avoid path escaping:
inserted = ktav.insert_value_segments(source, ["a.b", "x\\y"], "v")
renamed = ktav.rename_key_segments(source, ["a.b", "x\\y"], "z.w")
```

`insert_value` and `remove_value` take the same textual paths as
`edit_value`; the `_segments` forms take already-decoded literal
segments. Insert's final segment names a new Object key: its parent must
exist and be an Object, and an existing key is never overwritten. Array
insertion is unsupported. Remove accepts an existing value, including
an array element (later elements shift); emptied parent Objects remain
rather than being pruned. Rename addresses an Object member and takes
`new_key` as one literal name, not a path; dots and backslashes there
are ordinary characters. The member's position and value stay put, and
a name collision is rejected.

These operations splice source text rather than serializing the whole
document. Existing layout and unrelated text are preserved whenever a
lossless patch is possible; unsupported structural cases fail explicitly
instead of guessing. Empty segment lists and missing targets are errors.
The insert, remove and rename APIs are available with the native
backend. The pure-Python backend implements insert, remove and rename (including
`insert_value_segments`); their current readiness and conformance are pending CI
verification.

### 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.
Expand Down
10 changes: 10 additions & 0 deletions docs/ru/CHANGELOG.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,16 @@
путь), `KtavNotFoundError` и `KtavUnsupportedError`; тот же
десятипольный конверт, `error` — один из `EditInvalidPath` /
`EditNotFound` / `EditUnsupported`.
- `ktav.insert_value(source, path, value)` и
`ktav.insert_value_segments(source, segments, value)` добавляют новый
член Object без перезаписи существующего ключа. `ktav.remove_value(source, path)`
и `ktav.remove_value_segments(source, segments)` удаляют существующее
значение (элементы массива сдвигаются; пустые родительские Object остаются).
- `ktav.rename_key(source, path, new_key)` и
`ktav.rename_key_segments(source, segments, new_key)` переименовывают член Object
на месте; `new_key` — одно буквальное имя, а не dotted-путь.
Все шесть API выполняют lossless-splice исходника, доступны в native и
pure-Python backend и явно отклоняют неподдерживаемые структурные случаи.
- Корпус spec 0.9: conformance runner исполняет fixtures из
`versions/0.9/tests` (162 invalid — 72 новых диагностики
`diagnostics09` EOF/битый UTF-8), проверяет метаданные
Expand Down
32 changes: 32 additions & 0 deletions docs/ru/README.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,38 @@ byte-identical no-op, даже при неканоничном написани
нетронутые ветки остаются inline. Native и pure backend реализуют
идентичную семантику.

### Структурные правки исходника — вставка, удаление, переименование

```python
inserted = ktav.insert_value(source, "service.timeout", 30)
removed = ktav.remove_value(inserted, "service.old")
renamed = ktav.rename_key(removed, "service.timeout", "deadline")

# Literal-сегменты не требуют экранирования пути:
inserted = ktav.insert_value_segments(source, ["a.b", "x\\y"], "v")
renamed = ktav.rename_key_segments(source, ["a.b", "x\\y"], "z.w")
```

`insert_value` и `remove_value` принимают текстовые пути как
`edit_value`; варианты `_segments` принимают уже декодированные
literal-сегменты. Последний сегмент вставки задаёт новый ключ Object:
родитель должен существовать и быть Object, существующий ключ никогда
не перезаписывается. Вставка в Array не поддерживается. Удаление
принимает существующее значение, включая элемент массива (последующие
элементы сдвигаются); опустевшие родительские Object сохраняются.
Переименование адресует член Object, а `new_key` — одно буквальное имя,
не путь: точки и обратные косые черты в нём являются обычными символами.
Позиция и значение члена сохраняются; конфликт имени отклоняется.

Эти операции выполняют splice исходника, а не сериализуют весь документ.
Существующая раскладка и посторонний текст сохраняются, если возможна
lossless-правка; неподдерживаемые структурные случаи явно завершаются
ошибкой вместо догадок. Пустой список сегментов и отсутствующая цель —
ошибки. API вставки, удаления и переименования доступны с native
backend. Pure-Python backend реализует вставку, удаление и переименование
(включая `insert_value_segments`); их текущая готовность и соответствие
ожидают проверки CI.

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

Примеры относятся к ещё не выпущенному API 0.9, а не к опубликованному пакету 0.8.1. Они заменяют только существующие значения: не переименовывают ключи, не создают отсутствующие пути и не удаляют записи. Фрагменты независимы; Rust `?` предполагает внешнюю функцию с результатом `Result`. В Go panic используется только для фиксированных корректных данных примера; приложение должно обработать возвращённую ошибку.
Expand Down
9 changes: 9 additions & 0 deletions docs/zh/CHANGELOG.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,15 @@ Rust 实现见 [`ktav-lang/rust`](https://github.com/ktav-lang/rust)。
UTF-8 字节偏移十进制串)、`KtavNotFoundError` 与
`KtavUnsupportedError`;信封仍是同样的十字段,`error` 取
`EditInvalidPath` / `EditNotFound` / `EditUnsupported` 之一。
- `ktav.insert_value(source, path, value)` 与
`ktav.insert_value_segments(source, segments, value)` 新增 Object 成员,
不覆盖已有键。`ktav.remove_value(source, path)` 与
`ktav.remove_value_segments(source, segments)` 删除已有值(数组元素前移,
空的父 Object 保留)。
- `ktav.rename_key(source, path, new_key)` 与
`ktav.rename_key_segments(source, segments, new_key)` 原位重命名 Object 成员;
`new_key` 是一个字面键名,而非点分路径。六个 API 均通过无损源文本 splice
实现,native 与 pure-Python 后端均可用,并会明确拒绝不支持的结构情况。
- spec 0.9 语料:conformance 运行器现在执行 `versions/0.9/tests`
的 fixture(162 个 invalid —— 其中 72 个是新的 `diagnostics09`
EOF/坏 UTF-8 诊断),校验 `expected_location` 元数据(line、
Expand Down
26 changes: 26 additions & 0 deletions docs/zh/README.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,32 @@ dotted/reopen 目标、结构替换下的内部注释、或在目标上下文中
替换只展开被触及的 inline 包装层;未触及的嵌套分支保持 inline。
native 与 pure backend 实现完全一致的语义。

### 结构化源文本编辑 —— 插入、删除与重命名

```python
inserted = ktav.insert_value(source, "service.timeout", 30)
removed = ktav.remove_value(inserted, "service.old")
renamed = ktav.rename_key(removed, "service.timeout", "deadline")

# literal 段无需路径转义:
inserted = ktav.insert_value_segments(source, ["a.b", "x\\y"], "v")
renamed = ktav.rename_key_segments(source, ["a.b", "x\\y"], "z.w")
```

`insert_value` 和 `remove_value` 接受与 `edit_value` 相同的文本路径;
`_segments` 形式接受已解码的 literal 段。插入路径的最后一段是新
Object 键:父级必须存在且为 Object,已有键绝不会被覆盖。不支持向
Array 插入。删除接受既有值,包括数组元素(后续元素会前移);变空
的父 Object 不会被裁掉。重命名定位 Object 成员,`new_key` 是单个
literal 名称而非路径,其中的点号和反斜杠都是普通字符。成员位置与
值保持不变;名称冲突会被拒绝。

这些操作通过 splice 修改源文本,而不是序列化整个文档。只要存在
无损补丁,就保留已有布局及无关文本;不支持的结构情形会明确失败,
不会猜测。空段列表和不存在的目标均为错误。插入、删除与重命名 API
可在 native backend 中使用。Pure-Python backend 已实现插入、删除与重命名(包括
`insert_value_segments`);其当前就绪度与符合预期情况仍待 CI 验证。

### 源文本编辑示例

以下示例适用于尚未发布的 0.9 API,而非已发布的 0.8.1 包。只能替换已有值:不会重命名键、创建缺失路径或删除条目。各代码片段相互独立;Rust 的 `?` 假定外层函数返回 `Result`。Go 示例仅针对固定且有效的输入使用 panic;应用程序应处理返回的错误。
Expand Down
Loading
Loading