1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
//! [![Build Status](https://github.com/kurtlawrence/kserd/workflows/Rust/badge.svg)](https://github.com/kurtlawrence/kserd/actions) //! [![Latest Version](https://img.shields.io/crates/v/kserd.svg)](https://crates.io/crates/kserd) //! [![Rust Documentation](https://img.shields.io/badge/api-rustdoc-blue.svg)](https://docs.rs/kserd) //! [![codecov](https://codecov.io/gh/kurtlawrence/kserd/branch/master/graph/badge.svg)](https://codecov.io/gh/kurtlawrence/kserd) //! //! **K**urt's **S**elf **E**xplanatory **R**ust **D**ata. //! //! See the [rs docs.](https://docs.rs/kserd/) //! Look at progress and contribute on [github.](https://github.com/kurtlawrence/kserd) //! //! ## Introduction //! `kserd` provides a data structure to represent programmatic data (mainly for Rust). Data is held in //! enum variants covering the basic primitives along with nested structures such as tuples, //! containers, sequences, and maps. `kserd` tries to differentiate itself by providing the data //! structure as the in-memory intermediary between serialized format and a programming language's //! structure. The serialized format is inspired by TOML to make `kserd` as human-readable as possible. //! //! ## Getting Started //! With default features enabled, using `kserd` is a simple as importing the root which will contain //! all the important items. //! //! ```rust //! use kserd::*; //! //! # #[cfg(feature = "encode")] { //! // Kserd and Value are the building blocks of the data. //! let mut kserd = Kserd::with_id("greeting", Value::new_str("Hello")).unwrap(); //! //! // Kserd/Value are meant to be useable in their memory form //! // not just simple data holding structure! //! assert_eq!(kserd.str(), Some("Hello")); //! //! // you can mutate in place as well //! kserd.str_mut().map(|s| { s.push_str(", world!"); }); //! assert_eq!(kserd.str(), Some("Hello, world!")); //! //! // encode data structures that implement serde::Serialize //! let kserd = Kserd::enc(&vec![0, 1, 2, 4]).unwrap(); //! //! // can format the kserd into a human-readable string //! println!("{}", kserd.as_str()); // should print [0, 1, 2, 4] //! # } //! ``` //! //! It is recommended to consult the [api documentation](crate) as there is extensive examples and //! explanations. //! //! ## Features //! //! The kserd library is feature gated, but all features are enabled by default. //! //! | Feature | Description | Further reading | //! | -------- | ----------- | --------------- | //! | _encode_ | Convert data structures to and from `Kserd`. Makes use of `serde` `Serialize` and `Deserialize` traits. | [`kserd::encode`](crate::encode) | //! | _format_ | Format a `Kserd` to a human-readable string. | [`kserd::format`](crate::fmt) | //! | _parse_ | Parse a string into a `Kserd`. | [`kserd::parse`](crate::parse) | //! //! ## To `1.0` Stabilistations //! //! - [ ] stabilise `kserd_derive` crate //! - [ ] extra implementations for `ToKserd` //! - [ ] further testing of parsing to catch edge cases #![warn(missing_docs)] #![deny(intra_doc_link_resolution_failure)] // **************** no-feature ****************** /// The data structures, such as [`Kserd`] and [`Value`]. /// /// [`Kserd`]: ds::Kserd /// [`Value`]: ds::Value pub mod ds; pub mod nav; mod to_kserd; pub use self::{ ds::{Barr, Kserd, Kstr, Number, Value}, to_kserd::{ToKserd, ToKserdErr}, }; type List<'a> = Vec<Kserd<'a>>; type Fields<'a> = std::collections::BTreeMap<Kstr<'a>, Kserd<'a>>; type Map<'a> = std::collections::BTreeMap<Kserd<'a>, Kserd<'a>>; // **************** encode ********************** #[cfg(feature = "encode")] #[macro_use] extern crate serde; #[cfg(feature = "encode")] pub mod encode; // **************** format ********************** #[cfg(feature = "format")] pub mod fmt; // **************** parse *********************** /// Parse a string into a [`Kserd`]. /// /// Requires the _parse_ feature. /// /// [`Kserd`]: ds::Kserd #[cfg(feature = "parse")] pub mod parse;