rskit_codec/lib.rs
1//! Pluggable structured-text codecs over a shared value tree.
2//!
3//! `rskit-codec` provides a small, object-safe [`Codec`] contract for encoding
4//! and decoding structured text formats (TOML, JSON, …) through one canonical value model —
5//! [`serde_json::Value`]. Any crate that reads or writes a config file, manifest,
6//! or document reuses these codecs instead of re-implementing "bounded read → parse → typed error" per format.
7//!
8//! # Value model
9//!
10//! [`serde_json::Value`] is the canonical in-memory tree. It is format-neutral
11//! and the de-facto Rust interchange type, so TOML and JSON both decode into it
12//! and the [`value`] merge operates on it. One consequence:
13//! types without a JSON equivalent (notably TOML datetimes) are not part of the model —
14//! represent such values as strings.
15//!
16//! # Object safety
17//!
18//! [`Codec`] is object-safe (`Arc<dyn Codec>`)
19//! so a codec can be selected at runtime (e.g. by file extension via [`select`]). The generic,
20//! type-driven conveniences [`encode`] and [`decode`] are free functions taking `&dyn Codec`,
21//! keeping the trait object-safe while still supporting `#[derive(Serialize, Deserialize)]` types.
22//! `decode::<T>` honors `#[serde(deny_unknown_fields)]`.
23//!
24//! # Quick start
25//!
26//! ```
27//! use rskit_codec::{JsonCodec, decode, encode};
28//! use serde::{Deserialize, Serialize};
29//!
30//! #[derive(Serialize, Deserialize, PartialEq, Debug)]
31//! struct Settings {
32//! name: String,
33//! retries: u8,
34//! }
35//!
36//! let codec = JsonCodec::default();
37//! let parsed: Settings = decode(&codec, r#"{ "name": "svc", "retries": 3 }"#).unwrap();
38//! assert_eq!(parsed, Settings { name: "svc".into(), retries: 3 });
39//!
40//! let text = encode(&codec, &parsed).unwrap();
41//! assert!(text.contains("\"name\""));
42//! ```
43
44#![warn(missing_docs)]
45
46mod codec;
47pub mod framing;
48mod json;
49pub mod select;
50#[cfg(feature = "toml")]
51mod toml;
52pub mod value;
53
54pub use codec::{Codec, decode, encode};
55pub use json::{JsonCodec, JsonStyle};
56#[cfg(feature = "toml")]
57pub use toml::TomlCodec;
58
59/// Re-export of the canonical value model.
60pub use serde_json::Value;