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