kserd 0.5.0

Kurt's Self-Explanatory Rust Data
Documentation 
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

//! [![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) |

#![warn(missing_docs)]
#![deny(broken_intra_doc_links)]

// **************** 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;