{"id":13753458,"url":"https://github.com/kdl-org/kdl-rs","last_synced_at":"2025-05-14T15:11:03.926Z","repository":{"id":38080596,"uuid":"321528788","full_name":"kdl-org/kdl-rs","owner":"kdl-org","description":"Rust parser for KDL","archived":false,"fork":false,"pushed_at":"2025-04-28T18:26:09.000Z","size":421,"stargazers_count":372,"open_issues_count":21,"forks_count":35,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-28T19:34:29.259Z","etag":null,"topics":["kdl","rust"],"latest_commit_sha":null,"homepage":"https://docs.rs/kdl","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kdl-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["zkat"]}},"created_at":"2020-12-15T02:21:27.000Z","updated_at":"2025-04-28T18:26:13.000Z","dependencies_parsed_at":"2024-04-06T07:28:53.724Z","dependency_job_id":"63887702-1761-4cb9-9419-70c1eef72a77","html_url":"https://github.com/kdl-org/kdl-rs","commit_stats":{"total_commits":151,"total_committers":16,"mean_commits":9.4375,"dds":"0.19867549668874174","last_synced_commit":"05a4c4fce1a25727e15f4e2f873d0e0ca076c328"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdl-org%2Fkdl-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdl-org%2Fkdl-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdl-org%2Fkdl-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdl-org%2Fkdl-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kdl-org","download_url":"https://codeload.github.com/kdl-org/kdl-rs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254170056,"owners_count":22026219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kdl","rust"],"created_at":"2024-08-03T09:01:22.607Z","updated_at":"2025-05-14T15:11:03.920Z","avatar_url":"https://github.com/kdl-org.png","language":"Rust","funding_links":["https://github.com/sponsors/zkat"],"categories":["Rust","rust"],"sub_categories":[],"readme":"# `kdl`\n\n`kdl` is a \"document-oriented\" parser and API for the [KDL Document\nLanguage](https://kdl.dev), a node-based, human-friendly configuration and\nserialization format.\n\nUnlike serde-based implementations, this crate preserves formatting when\nediting, as well as when inserting or changing values with custom\nformatting. This is most useful when working with human-maintained KDL\nfiles.\n\nYou can think of this crate as\n[`toml_edit`](https://crates.io/crates/toml_edit), but for KDL.\n\nThis crate supports both KDL v2.0.0 and v1.0.0 (when using the non-default\n`v1` feature). It also supports converting documents between either format.\n\nThere is also a `v1-fallback` feature that may be enabled in order to have\nthe various `Kdl*::parse` methods try to parse their input as v2, and, if\nthat fails, try again as v1. In either case, a dedicated `Kdl*::parse_v1`\nmethod is available for v1-exclusive parsing, as long as either `v1` or\n`v1-fallback` are enabled.\n\n### Example\n\n```rust\nuse kdl::{KdlDocument, KdlValue};\n\nlet doc_str = r#\"\nhello 1 2 3\n\n// Comment\nworld prop=string-value {\n    child 1\n    child 2\n    child #inf\n}\n\"#;\n\nlet doc: KdlDocument = doc_str.parse().expect(\"failed to parse KDL\");\n\nassert_eq!(\n    doc.iter_args(\"hello\").collect::\u003cVec\u003c\u0026KdlValue\u003e\u003e(),\n    vec![\u00261.into(), \u00262.into(), \u00263.into()]\n);\n\nassert_eq!(\n    doc.get(\"world\").map(|node| \u0026node[\"prop\"]),\n    Some(\u0026\"string-value\".into())\n);\n\n// Documents fully roundtrip:\nassert_eq!(doc.to_string(), doc_str);\n```\n\n### Controlling Formatting\n\nBy default, everything is created with default formatting. You can parse\nitems manually to provide custom representations, comments, etc:\n\n```rust\nlet node_str = r#\"\n  // indented comment\n  \"formatted\" 1 /* comment */ \\\n    2;\n\"#;\n\nlet mut doc = kdl::KdlDocument::new();\ndoc.nodes_mut().push(node_str.parse().unwrap());\n\nassert_eq!(\u0026doc.to_string(), node_str);\n```\n\n[`KdlDocument`], [`KdlNode`], [`KdlEntry`], and [`KdlIdentifier`] can all\nbe parsed and managed this way.\n\n### Error Reporting\n\n[`KdlError`] implements [`miette::Diagnostic`] and can be used to display\ndetailed, pretty-printed diagnostic messages when using [`miette::Result`]\nand the `\"fancy\"` feature flag for `miette`:\n\n```toml\n# Cargo.toml\n[dependencies]\nmiette = { version = \"x.y.z\", features = [\"fancy\"] }\n```\n\n```rust\nfn main() -\u003e miette::Result\u003c()\u003e {\n    \"foo 1.\".parse::\u003ckdl::KdlDocument\u003e()?;\n    Ok(())\n}\n```\n\nThis will display a message like:\n```\nError:\n  × Expected valid value.\n   ╭────\n 1 │ foo 1.\n   ·     ─┬\n   ·      ╰── invalid float\n   ╰────\n  help: Floating point numbers must be base 10, and have numbers after the decimal point.\n```\n\n### Features\n\n* `span` (default) - Includes spans in the various document-related structs.\n* `v1` - Adds support for v1 parsing. This will pull in the entire previous\n  version of `kdl-rs`, and so may be fairly heavy.\n* `v1-fallback` - Implies `v1`. Makes it so the various `*::parse()` and\n  `FromStr` implementations try to parse their inputs as `v2`, and, if that\n  fails, try again with `v1`. For `KdlDocument`, a heuristic will be applied\n  if both `v1` and `v2` parsers fail, to pick which error(s) to return. For\n  other types, only the `v2` parser's errors will be returned.\n\n### Quirks\n\n#### Properties\n\nMultiple properties with the same name are allowed, and all duplicated\n**will be preserved**, meaning those documents will correctly round-trip.\nWhen using `node.get()`/`node[\"key\"]` \u0026 company, the _last_ property with\nthat name's value will be returned (as per spec).\n\n#### Numbers\n\nKDL itself does not specify a particular representation for numbers and\naccepts just about anything valid, no matter how large and how small. This\nmeans a few things:\n\n* Numbers without a decimal point are interpreted as [`i128`].\n* Numbers with a decimal point are interpreted as [`f64`].\n* The keywords `#inf`, `#-inf`, and `#nan` evaluate to [`f64::INFINITY`],\n  [`f64::NEG_INFINITY`], and [`f64::NAN`].\n* The original _representation/text_ of these numbers will be preserved,\n  unless you [`KdlDocument::autoformat`] in which case the original\n  representation will be thrown away and the actual value will be used when\n  serializing.\n\n### Minimum Supported Rust Version (MSRV)\n\nYou must be at least `1.81` tall to get on this ride.\n\n### License\n\nThe code in this repository is covered by [the Apache-2.0\nLicense](./LICENSE).\n\n[`KdlDocument`]: https://docs.rs/kdl/latest/kdl/struct.KdlDocument.html\n[`KdlNode`]: https://docs.rs/kdl/latest/kdl/struct.KdlNode.html\n[`KdlEntry`]: https://docs.rs/kdl/latest/kdl/struct.KdlEntry.html\n[`KdlIdentifier`]: https://docs.rs/kdl/latest/kdl/struct.KdlIdentifier.html\n[`KdlError`]: https://docs.rs/kdl/latest/kdl/struct.KdlError.html\n[`miette::Diagnostic`]: https://docs.rs/miette/latest/miette/trait.Diagnostic.html\n[`miette::Result`]: https://docs.rs/miette/latest/miette/type.Result.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdl-org%2Fkdl-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkdl-org%2Fkdl-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdl-org%2Fkdl-rs/lists"}