berkus
/
kdl-rs
mirror of https://github.com/kdl-org/kdl-rs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: readme updates

This commit is contained in:
Kat Marchán 2022-04-23 01:23:16 -07:00
parent d63f336d18
commit 21f7dbf106
No known key found for this signature in database
GPG Key ID: AEB529C08A3C7E9E
2 changed files with 42 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
README.md
View File

@ -1,13 +1,20 @@
# `kdl`
`kdl` is a "document-oriented" parser and API. That means that, unlike
serde-based implementations, it's meant to preserve formatting when
editing, as well as inserting values with custom formatting. This is
useful when working with human-maintained KDL files.
`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.
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.
### Example
```rust
@ -59,6 +66,29 @@ assert_eq!(&doc.to_string(), node_str);
[`KdlDocument`], [`KdlNode`], [`KdlEntry`], and [`KdlIdentifier`] can all
be parsed and managed this way.
This error implements [`miette::Diagnostic`] and can be used to display
detailed, pretty-printed diagnostic messages when using [`miette::Result`]
and the `"pretty"` feature flag for `miette`:
```rust
fn main() -> miette::Result<()> {
"foo 1.".parse::<kdl::KdlDocument>()?;
Ok(())
}
```
This will display a message like:
```
Error:
× Expected valid value.
╭────
1 │ foo 1.
· ─┬
· ╰── invalid float
╰────
help: Floating point numbers must be base 10, and have numbers after the decimal point.
```
### License
The code in this repository is covered by [the Apache-2.0

14
src/lib.rs
View File

@ -1,13 +1,15 @@
//! `kdl` is a "document-oriented" parser and API. That means that, unlike
//! serde-based implementations, it's meant to preserve formatting when
//! editing, as well as inserting values with custom formatting. This is
//! useful when working with human-maintained KDL files.
//! `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.
//!
//! 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
//! should check out [`knuffel`](https://crates.io/crates/knuffel) or
//! 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.
//!