Crate kfl

Source
Expand description

§KFL

mdbook

  • Nominal Typing
  • Trait-Based
  • Two-Level
  • Decode-Encode Dual
  • Literal

A KDL file format parser with great error reporting and convenient derive macros.

§About KDL

To give you some background on the KDL format. Here is a small example:

foo 1 "three" key="val" {
    bar
    (role)baz 1 2
}

Here is what are annotations for all the datum as described by the specification and this guide:

foo 1 "three" key="val" {                           ╮
─┬─ ┬ ───┬─── ────┬────                             │
 │  │    │        ╰───── property (can be multiple) │
 │  │    │                                          │
 │  ╰────┴────────────── arguments                  │
 │                                                  │
 ╰── node name                                      ├─ node "foo", with
                                                    │  "bar" and "baz"
    bar                                             │  being children
    (role)baz 1 2                                   │
     ──┬─                                           │
       ╰────── type name for node named "baz"       │
}                                                   ╯

§Usage

Most common usage of this library is using derive and [decode] or decode_children function:

use kfl::{Decode, DecodePartial, Encode};
use std::path::PathBuf;
#[cfg(feature = "http")]
use http::Uri;

#[derive(DecodePartial, Default)]
struct Document {
    #[kfl(children)]
    routes: Vec<Route>,
    #[kfl(children)]
    plugins: Vec<Plugin>,
}

#[derive(Decode, Encode)]
struct Route {
    #[kfl(argument)]
    path: PathBuf,
    #[kfl(children)]
    subroutes: Vec<Route>,
}

#[derive(Decode, Encode)]
struct Plugin {
    #[kfl(argument)]
    name: String,
    #[cfg(feature = "http")]
    #[kfl(property)]
    url: Uri,
}

let document = kfl::decode_children::<Document>("example.kdl", r#"
    route /api {
        route /api/v1
    }
    plugin "http" url=https://example.org/http
"#)?;

§License

Licensed under either of

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Re-exports§

pub use errors::Error;
pub use traits::Decode;
pub use traits::DecodePartial;
pub use traits::DecodeScalar;
pub use traits::Encode;
pub use traits::EncodePartial;
pub use traits::EncodeScalar;

Modules§

ast
Structures that represent abstract syntax tree (AST) of the KDL document
context
Decode support stuff
decode
Used by derive macro.
errors
Error types for the kfl library
print
Display implementation for ast
span
kfl supports to kinds of the span for parsing
traits
Traits used for the library

Macros§

own
Creates Box<str> from &str

Functions§

decode
Parse KDL text and decode it into Rust object
decode_children
Parse KDL text and decode Rust object
decode_with_context
Parse KDL text and decode Rust object providing extra context for the decoder
encode
Encode Rust object and print it into KDL text
encode_children
Parse KDL text and decode Rust object
parse
Parse KDL text and return AST
print
Print ast and return KDL text

Derive Macros§

Decode
DecodePartial
DecodeScalar
Encode
EncodePartial
EncodeScalar