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: 4 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,8 @@ jobs:
- uses: Swatinem/rust-cache@v2

- name: cargo test
env:
KTAV_REQUIRE_SPEC: '1'
run: cargo test --all-features --no-fail-fast

msrv:
Expand Down Expand Up @@ -113,4 +115,6 @@ jobs:
- uses: Swatinem/rust-cache@v2

- name: cargo test
env:
KTAV_REQUIRE_SPEC: '1'
run: cargo test --locked --all-features --no-fail-fast
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ For the format specification's own history, see the

## [Unreleased]

### Changed

- **Breaking in 0.9.0:** `InvalidUtf8` gains `line`/`span`; `UnclosedCompound` gains the opener's `line`. Downstream constructors and exhaustive field patterns must migrate. Direct Rust errors, public envelopes and C ABI source operations share raw-byte locations; UTF-8 spans are non-empty and EOF spans cover the innermost opener through EOF. LF, lone CR, CRLF and BOM offsets are preserved, including `Span::line_col` and envelope `line_text`. The ten-field JSON schema and I/O/writer location rules are unchanged. New regression oracles live only in the draft spec `versions/0.9/tests` and run across source entry points; CI refuses to skip a missing corpus. Version 0.9.0 is in preparation, not published.

### Added

- Rust-only source-editing API: `ktav::edit::edit_value` accepts an escaped dotted path, and `edit_value_segments` accepts a slice/vector of literal segments. Both replace an existing value without reformatting the document, preserve surrounding bytes and comments, and return a new `String`.
Expand All @@ -24,6 +28,7 @@ For the format specification's own history, see the
- Write nested inline replacements into one buffer; avoid temporary character vectors and a second copy of parsed textual path segments. Keep semantic verification and byte-preserving behavior. Add short paired benchmarks with separate compilation and an external 15-second process limit.
- The positional pass shares structural classifiers with the parser without constructing unused values or multiline bodies. Verify the edited target and untouched tree without cloning the replacement; render borrowed block compounds without a temporary root wrapper. Preserve validation, writer error paths and byte-for-byte output, with focused regression tests and expanded paired benchmarks.
- Borrow literal path slices and unescaped textual segments instead of copying each segment. Assemble raw-marker prefixes and unchanged replacement bodies directly into the result; render verbatim replacements in one buffer without an intermediate EOL-converted string. Preserve exact output and full semantic verification; measure text and segment paths separately in short paired benchmarks.
- Locate diagnostic line text by reverse terminator search instead of rescanning the document prefix. Probe JSON strings with safe eight-byte operations, bulk-copy unescaped UTF-8, specialize escaped ASCII and retain the Unicode encoder. Allocate reopen-merge child buffers and seen-key storage lazily. Preserve exact bytes and locations; add allocation/escaping regressions and paired runtime benchmarks with one external 15-second limit for the entire process batch.

## [0.8.1] — 2026-10-21

Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ Cargo-конвенцией: до 1.0 bump MINOR считается ломающ

## [Не выпущено]

### Изменено

- **Breaking в 0.9.0:** в `InvalidUtf8` добавлены `line`/`span`, в `UnclosedCompound` — `line` открывающего маркера. Downstream-конструкторы и patterns, перечисляющие все поля, требуют миграции. Прямые Rust-ошибки, публичный envelope и C ABI source operations используют общие координаты исходных байтов; UTF-8 spans непустые, EOF spans охватывают самый внутренний незакрытый opener до EOF. LF, одиночный CR, CRLF и BOM учитываются без нормализации, в том числе в `Span::line_col` и envelope `line_text`. Схема JSON из десяти полей и отсутствие позиций у I/O/writer не меняются. Новые regression oracles находятся только в draft спеки `versions/0.9/tests` и проверяются через source entry points; CI запрещает пропуск отсутствующего corpus. Версия 0.9.0 готовится, но не опубликована.

### Добавлено

- Rust API редактирования исходного текста: `ktav::edit::edit_value` принимает экранированный dotted-путь, `edit_value_segments` — слайс/вектор буквальных сегментов. Обе функции заменяют существующее значение без форматирования документа, сохраняют окружающие байты и комментарии и возвращают новый `String`.
Expand All @@ -24,6 +28,7 @@ Cargo-конвенцией: до 1.0 bump MINOR считается ломающ
- Вложенные inline-замены пишутся в один буфер, без временного вектора символов и повторного копирования разобранных сегментов текстового пути. Семантическая проверка и сохранение исходных байтов остаются. Добавлены короткие парные benchmarks с отдельной компиляцией и внешним лимитом 15 секунд на процесс.
- Позиционный проход использует общие с parser структурные классификаторы без построения ненужных значений и multiline-тел. Проверка цели и неизменной части дерева обходится без клонирования replacement; блочные контейнеры рендерятся по заимствованию без временной корневой обёртки. Валидация, пути writer-ошибок и точные выходные байты сохранены; добавлены регрессии и расширены парные benchmarks.
- Буквальные сегменты пути и сегменты текстового пути без escape заимствуются без копирования каждого сегмента. Префиксы raw-маркера и тела замен, не требующие преобразования, переносятся непосредственно в результат; verbatim-замены рендерятся в один буфер без промежуточной строки с преобразованными EOL. Точные выходные байты и полная семантическая проверка сохранены; короткие парные benchmarks отдельно измеряют text- и segments-пути.
- Строка диагностики находится обратным поиском терминатора без повторного прохода по префиксу документа. JSON-строки проверяются безопасными восьмибайтовыми операциями; UTF-8 без escapes переносится целиком, экранируемый ASCII обрабатывается специализированно, Unicode encoder сохраняется. Дочерние буферы и хранилища seen-ключей reopen-merge выделяются лениво. Точные байты и координаты сохранены; добавлены регрессии аллокаций/экранирования и парные runtime benchmarks с единым внешним лимитом 15 секунд на весь batch процессов.

## [0.8.1] — 2026-10-21

Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@

## [尚未发布]

### 变更

- **0.9.0 破坏性变更:** `InvalidUtf8` 新增 `line`/`span`,`UnclosedCompound` 新增起始标记的 `line`。下游构造器及枚举全部字段的模式需要迁移。直接 Rust 错误、公开 envelope 和 C ABI 源操作共用原始字节坐标;UTF-8 区间非空,EOF 区间覆盖最内层未闭合起始标记至 EOF。LF、单独 CR、CRLF 及 BOM 均不经规范化,`Span::line_col` 和 envelope 的 `line_text` 同样遵守该规则。十字段 JSON 格式及 I/O/writer 无源位置的规则不变。新增回归 oracle 仅位于规范草案 `versions/0.9/tests`,由各源入口执行;CI 不允许因语料缺失而跳过。0.9.0 尚在准备中,未发布。

### 新增

- Rust 源文本编辑 API:`ktav::edit::edit_value` 接受带转义的点分路径,`edit_value_segments` 接受字面路径段切片/向量。两者均在不重新格式化文档的情况下替换已有值,保留周围字节与注释,并返回新的 `String`。
Expand All @@ -24,6 +28,7 @@
- 将嵌套行内替换直接写入同一缓冲区,避免临时字符向量及文本路径段的二次复制。保留语义验证和原始字节保护。新增短时配对基准,编译独立进行,每个进程由外部工具限制为 15 秒。
- 位置扫描与解析器共用结构分类,不再构造无用值或多行正文。验证目标和未修改的树时不再克隆替换值;以借用方式渲染块容器,避免临时根包装。保留验证、writer 错误路径和逐字节输出,并增加专项回归测试及配对基准场景。
- 借用字面路径段及不含转义的文本路径段,不再逐段复制。将 raw 标记前缀及无需转换的替换正文直接写入结果;verbatim 替换使用单一缓冲区,不再生成转换 EOL 的中间字符串。保留精确输出与完整语义验证;短时配对基准分别测量文本路径和路径段 API。
- 通过反向查找换行符定位诊断行,不再重复扫描文档前缀。用安全的八字节运算检查 JSON 字符串,整体复制无需转义的 UTF-8,专门处理需转义的 ASCII,并保留 Unicode encoder。按需分配 reopen-merge 子缓冲区和 seen 键存储。保留精确字节与坐标;增加分配及转义回归测试,并提供配对 runtime 基准,整个进程 batch 共用一个外部 15 秒限制。

## [0.8.1] — 2026-10-21

Expand Down
8 changes: 6 additions & 2 deletions Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "ktav"
version = "0.8.1"
version = "0.9.0"
edition = "2021"
description = "Ktav — a plain configuration format. Three rules, zero indentation, zero quoting. Serde-native."
license = "MIT OR Apache-2.0"
Expand Down Expand Up @@ -38,7 +38,7 @@ exclude = [
# Which version of the Ktav format specification this crate implements.
# See https://github.com/ktav-lang/spec for the formal document.
[package.metadata.ktav]
spec-version = "0.8.1"
spec-version = "0.9.0"

[dependencies]
serde = { version = "1", features = ["derive"] }
Expand Down Expand Up @@ -107,3 +107,7 @@ harness = false
[[bench]]
name = "source_edit"
harness = false

[[bench]]
name = "runtime_paths"
harness = false
31 changes: 23 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,11 @@

**Playground:** convert JSON / YAML / TOML / INI ⇄ Ktav in your browser at **[ktav-lang.github.io](https://ktav-lang.github.io/)**.

**Specification:** this crate implements **Ktav 0.8.0**, the version
named by `[package.metadata.ktav] spec-version` in `Cargo.toml`. The
format is versioned and maintained independently of this crate — the two
numbers move apart on purpose, since a crate release that changes no
format behaviour leaves `spec-version` where it was. See
[`ktav-lang/spec`](https://github.com/ktav-lang/spec) for the formal
document, and [`CHANGELOG.md`](CHANGELOG.md) for this crate's history.
**Version in preparation: 0.9.0, not published.** This branch combines
lossless source editing by path and the new source-error location model.
`Cargo.toml` targets the draft spec corpus `versions/0.9/tests`; published
0.8.1 remains unchanged. See [`ktav-lang/spec`](https://github.com/ktav-lang/spec)
for the specification and [`CHANGELOG.md`](CHANGELOG.md) for the migration.

---

Expand Down Expand Up @@ -503,6 +501,20 @@ the target numeric type; a value that arrived as a string (e.g. forced
with `::`) is still accepted via `FromStr`. `NaN` / `±Infinity` are
rejected by the serializer (Ktav does not represent them).

## Error model migration (0.9)

**0.9 migration (breaking):** `Error::InvalidUtf8` now contains
`{ valid_up_to, line, span }`; `ErrorKind::UnclosedCompound` contains
`{ kind, line, span }`. Update downstream constructors with the new fields;
use `..` in patterns when only selected fields matter. `line()` now returns
the source line for both errors. UTF-8 spans cover original malformed bytes;
EOF diagnostics cover the innermost opener through EOF and report its line.
Coordinates preserve BOM and LF/CR/CRLF; `Span::line_col` and envelope
`line_text` recognize all three terminators. I/O and writer failures retain
absent source positions. The ten-field JSON schema below is unchanged.
The new location oracles live in the draft `versions/0.9/tests` spec corpus;
this working version has not been published.

## Examples: Ktav → JSON5

JSON5 is on the right because it reads like ordinary JavaScript, allows
Expand Down Expand Up @@ -961,9 +973,12 @@ their parent module.

## Installation

The published dependency below is 0.8.1; it does not include the new path
editing or 0.9 error model. Version 0.9.0 currently requires this source checkout.

```toml
[dependencies]
ktav = "0.8.0"
ktav = "0.8.1"
serde = { version = "1", features = ["derive"] }
```

Expand Down
33 changes: 25 additions & 8 deletions README.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,12 @@

**Песочница:** конвертация JSON / YAML / TOML / INI ⇄ Ktav прямо в браузере — **[ktav-lang.github.io](https://ktav-lang.github.io/)**.

**Спецификация:** этот crate реализует **Ktav 0.8.0** — версию,
указанную в `[package.metadata.ktav] spec-version` в `Cargo.toml`.
Формат версионируется и поддерживается независимо от crate-а, и два
номера намеренно расходятся: выпуск crate-а, не меняющий поведение
формата, оставляет `spec-version` на месте. См.
[`ktav-lang/spec`](https://github.com/ktav-lang/spec) для канонического
документа и [`CHANGELOG.ru.md`](CHANGELOG.ru.md) — историю crate-а.
**Готовится версия 0.9.0, ещё не опубликована.** Эта ветка объединяет
lossless-редактирование исходного текста по пути и новую модель координат
ошибок. `Cargo.toml` указывает на draft corpus спеки `versions/0.9/tests`;
опубликованная 0.8.1 не меняется. Спецификация —
[`ktav-lang/spec`](https://github.com/ktav-lang/spec), миграция —
[`CHANGELOG.ru.md`](CHANGELOG.ru.md).

---

Expand Down Expand Up @@ -508,6 +507,21 @@ assert_eq!(keys, ["port", "host"]);
через `FromStr`. `NaN` / `±Infinity` отвергаются сериализатором
(Ktav их не представляет).

## Миграция модели ошибок (0.9)

**Миграция 0.9 (breaking):** `Error::InvalidUtf8` теперь содержит
`{ valid_up_to, line, span }`, `ErrorKind::UnclosedCompound` —
`{ kind, line, span }`. В downstream-конструкторах нужно заполнить новые
поля; в patterns используйте `..`, если важна только часть полей.
`line()` теперь возвращает исходную строку обеих ошибок. UTF-8 span
покрывает исходные ошибочные байты; EOF-диагностика охватывает самый
внутренний незакрытый opener до EOF и указывает его строку. Координаты
сохраняют BOM и LF/CR/CRLF; `Span::line_col` и envelope `line_text`
учитывают все три терминатора. Ошибки I/O и writer по-прежнему не имеют
позиции исходника. Схема JSON из десяти полей ниже не меняется. Новые
oracles координат находятся в draft corpus спеки `versions/0.9/tests`;
эта рабочая версия ещё не опубликована.

## Примеры: Ktav → JSON5

JSON5 справа потому, что читается как обычный JavaScript, допускает
Expand Down Expand Up @@ -971,9 +985,12 @@ ktav/

## Установка

Ниже указана опубликованная 0.8.1: в ней нет новых методов редактирования
по пути и модели ошибок 0.9. Для готовящейся 0.9.0 пока нужен этот source checkout.

```toml
[dependencies]
ktav = "0.8.0"
ktav = "0.8.1"
serde = { version = "1", features = ["derive"] }
```

Expand Down
26 changes: 20 additions & 6 deletions README.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,10 @@

**演练场:** 在浏览器中互转 JSON / YAML / TOML / INI ⇄ Ktav — **[ktav-lang.github.io](https://ktav-lang.github.io/)**。

**规范:** 本 crate 实现 **Ktav 0.8.0**,即 `Cargo.toml` 中
`[package.metadata.ktav] spec-version` 所指定的版本。格式与 crate 彼此
独立地版本化与维护,两个号码会有意分开——不改变格式行为的 crate 发布会
让 `spec-version` 保持原样。规范正文见
[`ktav-lang/spec`](https://github.com/ktav-lang/spec),crate 的历史见
**0.9.0 正在准备中,尚未发布。** 本分支同时包含按路径无损编辑源文本
及新的源错误坐标模型。`Cargo.toml` 指向规范草案语料 `versions/0.9/tests`;
已发布的 0.8.1 保持不变。规范见
[`ktav-lang/spec`](https://github.com/ktav-lang/spec),迁移说明见
[`CHANGELOG.zh.md`](CHANGELOG.zh.md)。

---
Expand Down Expand Up @@ -466,6 +465,18 @@ Rust 数值类型(`u8`..`u128`、`i8`..`i128`、`usize`、`isize`、`f32`、
(例如用 `::` 强制的)仍通过 `FromStr` 接受。`NaN` / `±Infinity` 会被
序列化器拒绝(Ktav 不表示这些值)。

## 错误模型迁移(0.9)

**0.9 迁移(破坏性变更):** `Error::InvalidUtf8` 现在包含
`{ valid_up_to, line, span }`,`ErrorKind::UnclosedCompound` 包含
`{ kind, line, span }`。下游构造器需要填写新增字段;只关注部分字段时,
模式应使用 `..`。两种错误的 `line()` 都返回源行号。UTF-8 区间覆盖原始
错误字节;EOF 诊断覆盖最内层未闭合起始标记至 EOF,并报告起始标记所在行。
坐标保留 BOM 及 LF/CR/CRLF;`Span::line_col` 和 envelope 的 `line_text`
识别全部三种换行形式。I/O 及 writer 错误仍不携带源位置。下述十字段 JSON
格式不变。新增位置 oracle 位于规范草案的 `versions/0.9/tests`;
当前工作版本尚未发布。

## 示例:Ktav → JSON5

右侧使用 JSON5,因为它读起来像普通 JavaScript,允许注释,并且
Expand Down Expand Up @@ -899,9 +910,12 @@ ktav/

## 安装

下面的依赖为已发布的 0.8.1,不包含新增路径编辑 API 或 0.9 错误模型。
准备中的 0.9.0 目前需要使用本源代码 checkout。

```toml
[dependencies]
ktav = "0.8.0"
ktav = "0.8.1"
serde = { version = "1", features = ["derive"] }
```

Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ release within a few days.

| Version | Supported |
|---------|--------------------|
| 0.8.x | ✅ |
| 0.9.x | ✅ |
| older | ❌ — upgrade first |

## Reporting a vulnerability
Expand Down
2 changes: 1 addition & 1 deletion SECURITY.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

| Версия | Поддерживается |
|---------|------------------------|
| 0.8.x | ✅ |
| 0.9.x | ✅ |
| старше | ❌ — сперва обновитесь |

## Сообщение об уязвимости
Expand Down
2 changes: 1 addition & 1 deletion SECURITY.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@

| 版本 | 支持 |
|---------|------------------------|
| 0.8.x | ✅ |
| 0.9.x | ✅ |
| 更早 | ❌ —— 请先升级 |

## 上报漏洞
Expand Down
Loading
Loading