kdl: KDL 2.0 parser, writer and struct marshaler (consensus version)

[davlgd]

kdl: KDL 2.0 parser, writer and struct marshaler

@Jengro777, this is the consensus version we discussed in vlang/v#28819, built from your implementation and mine; the details of what comes from where are below. It is opened here because vlang/kdl is still empty and cannot take a pull request yet; it replaces the current content of this repository, in six commits.

kdl reads and writes KDL 2.0 documents and maps them to V structs.

import kdl

doc := kdl.parse(text)!
port := doc.get('server')?.prop('port').as_int() or { 80 }
println(doc) // canonical KDL 2.0

cfg := kdl.decode[Config](text, rename: .kebab_case)!
println(kdl.encode(cfg)!)

A document is a list of nodes; a node has a name, arguments, properties and children; a value is string | i64 | f64 | bool | Null | BigInt with an optional type annotation. Syntax errors carry a line and a column. The writer produces the canonical form of the specification. encode and decode map a struct to a document: each field is a node, scalars inside a node are properties, structs and lists are children, and field tags (arg, args, props, child, omitempty, skip) cover the other layouts. Decoding fills the fields it finds, keeps defaults for the others, ignores what it does not know, and reports the rest with a typed error and a path such as server.route[1].timeout: expected f64, got string.

The module passes the official kdl-org test suite, vendored in tests/test_cases: the 95 invalid documents are rejected, the 243 valid ones produce the expected canonical output (floats compared as f64) and round-trip.

Where it comes from

This merges the two implementations proposed for vlib, vlang/v#28819 and vlang/v#27724 (vlang-community/kdl). The parser, writer and data model are those of #28819, the smaller of the two and the one that passed the whole official suite. The struct marshaling, its tags and its examples come from #27724, rewritten on this data model with stricter decoding: typed errors instead of silent coercions, and the struct validated before any data is read. Commits that reuse that work carry Co-authored-by: Jengro777.

Two features of #27724 are left out for now and will each get an issue: the relaxed parsing modes (NGINX-style identifiers, key: value, 10ms) and a writer that keeps the original formatting and comments.

Compilers and performance

The tests run with the new compiler, with the automatic fallback disabled, and with -old-compiler; CI covers Linux, macOS and Windows on V master plus an old-compiler job. A few constructs are written in a specific way to work around compiler behaviour, each with a comment in the code: with the old compiler under -prod, passing a large struct by value before every call made the writer quadratic (vlang/v#28418), so the internals pass references; with the new compiler, options are unwrapped with or rather than if x := opt inside generics, nodes are built in place rather than pushed as filled locals, and one wrong-code case around strings.Builder is avoided by binding an if expression first (a reproducer will be reported).

Parsing and encoding allocate about 2 KB per node, so on documents beyond roughly 100 000 nodes the Boehm collector dominates: 640 000 flat nodes (35 MB) parse in 12.7 s by default and in 0.7 s with GC_INITIAL_HEAP_SIZE=8G, which the README documents. Reducing that footprint would change the public types and make the API less direct (properties as an ordered list instead of a map, an annotation flag instead of ?string), so it is left for a later discussion.

[Copilot]

Copilot review overview

🟡 Changes recommended

Schema validation currently occurs after parsing, and optional omitempty fields are encoded incorrectly.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Validate schema before parsing input · New
• Apply omitempty to unwrapped optional values · New
• Correct walk example's comment handling description · New

What changed in this PR

Replaces the previous implementation with a consensus KDL 2.0 parser, canonical writer, data model, and V struct marshaler.

Changes:

• Adds strict parsing, writing, typed accessors, and struct encoding/decoding.
• Vendors the official conformance suite and adds extensive tests.
• Reorganizes examples, documentation, licensing, and CI.

File	Description
kdl.v	Defines the public data model and accessors.
parser.v	Implements KDL 2.0 parsing.
scanner.v	Handles tokens, numbers, Unicode, and escapes.
writer.v	Produces canonical KDL output.
marshal.v	Implements struct encoding and decoding.
*_test.v	Tests parsing, writing, marshaling, regressions, fuzzing, and conformance.
examples/​**	Adds updated usage examples.
tests/​test_cases/​input/​**	Vendors 338 official parser fixtures.
tests/​test_cases/​expected_kdl/​**	Vendors expected output for valid fixtures.
tests/​test_cases/​{README,LICENSE,CC-BY-SA-4.0}.txt	Documents fixture provenance and licensing.
coerce/​**, document/​**, parser/​**, relaxed/​**, tokenizer/​**	Removes the superseded implementation.
example/​**, tests/​{document,options,unicode}_test.v	Removes obsolete examples and tests.
README.md, LICENSE, v.mod	Updates API documentation, licensing, and metadata.
.github/​workflows/​ci.yml	Tests both V compilers across supported platforms.
.gitattributes, .gitignore	Configures fixture preservation and build exclusions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Decoding has schema-validation and numeric-underflow defects, and Windows CI can pass without running module checks.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 4 · 1

Open (5)

• Ensure Windows matrix failures cannot be masked · New
• Reject nonzero f64 values that underflow to f32 zero · New
• Apply omitempty to unwrapped optional values
• Validate schema before parsing input
• Correct walk example's comment handling description

[Copilot]

Copilot review overview

🟡 Changes recommended

Schema-validation ordering, optional omitempty behavior, and skipped Windows validation leave correctness and coverage gaps.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Ensure Windows bootstrap failures block the matrix · New
• Validate schema before parsing input · New
• Align walk example with supported parsed tree data · New

Resolved since last review (5)

• Reject nonzero f64 values that underflow to f32 zero
• Ensure Windows matrix failures cannot be masked
• Apply omitempty to unwrapped optional values
• Validate schema before parsing input
• Correct walk example's comment handling description

[Copilot]

Copilot review overview

🟡 Changes recommended

BOM-prefixed error columns and enum omitempty behavior are currently incorrect.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 2

Open (2)

• Treat zero-valued enums as empty for omitempty · New
• Correct line columns after skipping UTF-8 BOM · New

Resolved since last review (3)

• Validate schema before parsing input
• Ensure Windows bootstrap failures block the matrix
• Align walk example with supported parsed tree data

[Copilot]

Copilot review overview

🟡 Changes recommended

Optional-struct decoding can discard configured defaults, and one schema error template is grammatically incorrect.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Preserve defaults when decoding present optional structs · New
• Fix generated schema error article grammar · New

Resolved since last review (2)

• Correct line columns after skipping UTF-8 BOM
• Treat zero-valued enums as empty for omitempty

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Jengro777]

Although the PR has been merged, the code organization is not very good.
Files of the same type should be merged into folders instead of all being spread out.
This is not conducive to maintenance.