mirror of https://github.com/kdl-org/kdl-rs.git
docs: update readme and changelog
This commit is contained in:
Kat Marchán
parent
0c59b29a03
commit
38ae41c86a
30
CHANGELOG.md
30
CHANGELOG.md
|
|
@ -1,5 +1,35 @@
|
|||
# `kdl` Release Changelog
|
||||
|
||||
<a name="6.0.0"></a>
|
||||
## 6.0.0 (2024-12-22)
|
||||
|
||||
This release updates `kdl-rs` to support the latest [KDL 2.0.0
|
||||
spec](https://github.com/kdl-org/kdl/blob/2.0.0/SPEC.md).
|
||||
|
||||
Additionally, KDL 1.0.0 support has been retained behind `v1` and `v1-fallback`
|
||||
feature flags. This version of `kdl-rs` is able to convert back and forth
|
||||
between each.
|
||||
|
||||
### Features
|
||||
|
||||
* **compliance:** update to latest 2.0 spec (#103) ([4734b060](https://github.com/kdl-org/kdl-rs/commit/4734b0601b9f8bf7232f9bc97fdb31117ebcb4d5))
|
||||
* **api:** update the KdlNode and KdlDocument APIs to be more Vec-like (#101) ([683e87a1](https://github.com/kdl-org/kdl-rs/commit/683e87a1424e7925304b28d1b35420f8ff533d6a))
|
||||
* **v1:** add rudimentary, optional, KDL v1 parsing (#104) ([6a7248c4](https://github.com/kdl-org/kdl-rs/commit/6a7248c40516dc8e25fab81179b5677b3ab4823b))
|
||||
* **v1:** Add utility to auto-translate v1 to v2 ([c486cda7](https://github.com/kdl-org/kdl-rs/commit/c486cda7a5e4db5d80a58df6ce4a39442308afe9))
|
||||
* **error:** Rename KdlParseFailure back to KdlError ([12b2fd2f](https://github.com/kdl-org/kdl-rs/commit/12b2fd2f4f58ba9b112842098bd041f527d04dc4))
|
||||
* **v1:** add v2 -> v1 translation and fix translations to not autoformat ([b332eed4](https://github.com/kdl-org/kdl-rs/commit/b332eed4a0d91425cc620aed7895fec99520a287))
|
||||
* **compliance:** pull in final extra tests and change VT to newline ([3e8b2f44](https://github.com/kdl-org/kdl-rs/commit/3e8b2f443a44ba40d6ba3e370d8292eff2a81381))
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
* **v1:** remove v1 from default features ([3e5d7a33](https://github.com/kdl-org/kdl-rs/commit/3e5d7a33afbec0cb82c717209eecf87fb3617d0a))
|
||||
* **clippy:** clippy fixes ([4cbc3224](https://github.com/kdl-org/kdl-rs/commit/4cbc32246c8ef0469e50166125036417e1f00bc6))
|
||||
* **autoformat:** fix autoformatting of v1 -> v2 ([37255b0b](https://github.com/kdl-org/kdl-rs/commit/37255b0bf67efed88ed670f79cdc50e8879e0e1c))
|
||||
* **misc:** other tiny clippy/fmt issues ([ec73cdfa](https://github.com/kdl-org/kdl-rs/commit/ec73cdfa05c6486ff74bd84f8077341c9a7ec55e))
|
||||
* **v1:** sigh. forgot to remove v1 from default features again ([fef7c58b](https://github.com/kdl-org/kdl-rs/commit/fef7c58b02c493cc458d8080ade71987dabb0c76))
|
||||
* **clippy:** clippy fixes ([b097c7e2](https://github.com/kdl-org/kdl-rs/commit/b097c7e21b3b8dd92bc112f126672a8810d2d711))
|
||||
* **fmt:** cargo fmt ([0c59b29a](https://github.com/kdl-org/kdl-rs/commit/0c59b29a03d165b4af2864b3067e5f600545bb95))
|
||||
|
||||
<a name="6.0.0-alpha.5"></a>
|
||||
## 6.0.0-alpha.5 (2024-12-16)
|
||||
|
||||
|
|
|
|||
44
README.md
44
README.md
|
|
@ -2,32 +2,35 @@
|
|||
|
||||
`kdl` is a "document-oriented" parser and API for the [KDL Document
|
||||
Language](https://kdl.dev), a node-based, human-friendly configuration and
|
||||
serialization format. Unlike serde-based implementations, this crate
|
||||
preserves formatting when editing, as well as when inserting or changing
|
||||
values with custom formatting. This is most useful when working with
|
||||
human-maintained KDL files.
|
||||
serialization format.
|
||||
|
||||
Unlike serde-based implementations, this crate preserves formatting when
|
||||
editing, as well as when inserting or changing values with custom
|
||||
formatting. This is most useful when working with human-maintained KDL
|
||||
files.
|
||||
|
||||
You can think of this crate as
|
||||
[`toml_edit`](https://crates.io/crates/toml_edit), but for KDL.
|
||||
|
||||
If you don't care about formatting or programmatic manipulation, you might
|
||||
check out [`knuffel`](https://crates.io/crates/knuffel) or
|
||||
[`kaydle`](https://crates.io/crates/kaydle) instead for serde (or
|
||||
serde-like) parsing.
|
||||
This crate supports both KDL v2.0.0 and v1.0.0 (when using the non-default
|
||||
`v1` feature). It also supports converting documents between either format.
|
||||
|
||||
This crate supports parsing [KDL
|
||||
2.0.0-draft.6](https://github.com/kdl-org/kdl/releases/tag/2.0.0-draft.6)
|
||||
There is also a `v1-fallback` feature that may be enabled in order to have
|
||||
the various `Kdl*::parse` methods try to parse their input as v2, and, if
|
||||
that fails, try again as v1. In either case, a dedicated `Kdl*::parse_v1`
|
||||
method is available for v1-exclusive parsing, as long as either `v1` or
|
||||
`v1-fallback` are enabled.
|
||||
|
||||
### Example
|
||||
|
||||
```rust
|
||||
use kdl::KdlDocument;
|
||||
use kdl::{KdlDocument, KdlValue};
|
||||
|
||||
let doc_str = r#"
|
||||
hello 1 2 3
|
||||
|
||||
// Comment
|
||||
world prop=value {
|
||||
world prop=string-value {
|
||||
child 1
|
||||
child 2
|
||||
child #inf
|
||||
|
|
@ -37,13 +40,13 @@ world prop=value {
|
|||
let doc: KdlDocument = doc_str.parse().expect("failed to parse KDL");
|
||||
|
||||
assert_eq!(
|
||||
doc.get_args("hello"),
|
||||
doc.iter_args("hello").collect::<Vec<&KdlValue>>(),
|
||||
vec![&1.into(), &2.into(), &3.into()]
|
||||
);
|
||||
|
||||
assert_eq!(
|
||||
doc.get("world").map(|node| &node["prop"]),
|
||||
Some(&"value".into())
|
||||
Some(&"string-value".into())
|
||||
);
|
||||
|
||||
// Documents fully roundtrip:
|
||||
|
|
@ -102,6 +105,17 @@ Error:
|
|||
help: Floating point numbers must be base 10, and have numbers after the decimal point.
|
||||
```
|
||||
|
||||
### Features
|
||||
|
||||
* `span` (default) - Includes spans in the various document-related structs.
|
||||
* `v1` - Adds support for v1 parsing. This will pull in the entire previous
|
||||
version of `kdl-rs`, and so may be fairly heavy.
|
||||
* `v1-fallback` - Implies `v1`. Makes it so the various `*::parse()` and
|
||||
`FromStr` implementations try to parse their inputs as `v2`, and, if that
|
||||
fails, try again with `v1`. Errors will only be reported as if the input was
|
||||
`v2`. To manage this more precisely, you can use the `*::parse_v2` and
|
||||
`*::parse_v1` methods.
|
||||
|
||||
### Quirks
|
||||
|
||||
#### Properties
|
||||
|
|
@ -109,7 +123,7 @@ Error:
|
|||
Multiple properties with the same name are allowed, and all duplicated
|
||||
**will be preserved**, meaning those documents will correctly round-trip.
|
||||
When using `node.get()`/`node["key"]` & company, the _last_ property with
|
||||
that name's value will be returned.
|
||||
that name's value will be returned (as per spec).
|
||||
|
||||
#### Numbers
|
||||
|
||||
|
|
|
|||
23
src/lib.rs
23
src/lib.rs
|
|
@ -11,7 +11,7 @@
|
|||
//! [`toml_edit`](https://crates.io/crates/toml_edit), but for KDL.
|
||||
//!
|
||||
//! This crate supports both KDL v2.0.0 and v1.0.0 (when using the non-default
|
||||
//! `v1` feature).
|
||||
//! `v1` feature). It also supports converting documents between either format.
|
||||
//!
|
||||
//! There is also a `v1-fallback` feature that may be enabled in order to have
|
||||
//! the various `Kdl*::parse` methods try to parse their input as v2, and, if
|
||||
|
|
@ -19,12 +19,6 @@
|
|||
//! method is available for v1-exclusive parsing, as long as either `v1` or
|
||||
//! `v1-fallback` are enabled.
|
||||
//!
|
||||
//! Autoformatting a document parsed from a v1 doc will translate the document
|
||||
//! to v2 format, preserving as much of the v1 trivia as possible (comments,
|
||||
//! etc). It *should* generate a fully valid v2 document, but there may still be
|
||||
//! some corner cases that don't translate well. Please file issues as needed
|
||||
//! for those.
|
||||
//!
|
||||
//! ## Example
|
||||
//!
|
||||
//! ```rust
|
||||
|
|
@ -34,7 +28,7 @@
|
|||
//! hello 1 2 3
|
||||
//!
|
||||
//! // Comment
|
||||
//! world prop=value {
|
||||
//! world prop=string-value {
|
||||
//! child 1
|
||||
//! child 2
|
||||
//! child #inf
|
||||
|
|
@ -50,7 +44,7 @@
|
|||
//!
|
||||
//! assert_eq!(
|
||||
//! doc.get("world").map(|node| &node["prop"]),
|
||||
//! Some(&"value".into())
|
||||
//! Some(&"string-value".into())
|
||||
//! );
|
||||
//!
|
||||
//! // Documents fully roundtrip:
|
||||
|
|
@ -109,6 +103,17 @@
|
|||
//! help: Floating point numbers must be base 10, and have numbers after the decimal point.
|
||||
//! ```
|
||||
//!
|
||||
//! ## Features
|
||||
//!
|
||||
//! * `span` (default) - Includes spans in the various document-related structs.
|
||||
//! * `v1` - Adds support for v1 parsing. This will pull in the entire previous
|
||||
//! version of `kdl-rs`, and so may be fairly heavy.
|
||||
//! * `v1-fallback` - Implies `v1`. Makes it so the various `*::parse()` and
|
||||
//! `FromStr` implementations try to parse their inputs as `v2`, and, if that
|
||||
//! fails, try again with `v1`. Errors will only be reported as if the input was
|
||||
//! `v2`. To manage this more precisely, you can use the `*::parse_v2` and
|
||||
//! `*::parse_v1` methods.
|
||||
//!
|
||||
//! ## Quirks
|
||||
//!
|
||||
//! ### Properties
|
||||
|
|
|
|||
Loading…
Reference in New Issue