112 lines
2.9 KiB
Markdown
112 lines
2.9 KiB
Markdown
# wson
|
|
|
|
Rust implementation of the WSON text format and JBON binary format, with serde support.
|
|
|
|
## Features
|
|
|
|
- Serde API for ordinary acyclic Rust data:
|
|
- text: `wson::to_string`, `wson::from_str`
|
|
- binary JBON: `wson::to_vec`, `wson::from_slice`
|
|
- Graph API for WSON reference/cycle support:
|
|
- text references: `(0){"child":$0}`
|
|
- binary references: marker `0x06` for ids and `0x05` for references
|
|
- Java-compatible defaults from `net.woggioni:wson`:
|
|
- sorted objects (`BTreeMap`)
|
|
- parser `max_depth = 1_048_576`
|
|
- `serialize_references = false` unless enabled
|
|
- Signed zigzag LEB128 and byte-reversed double encoding compatible with `net.woggioni:jwo`.
|
|
|
|
## Quick start
|
|
|
|
```toml
|
|
[dependencies]
|
|
serde = { version = "1.0", features = ["derive"] }
|
|
wson = "0.1"
|
|
```
|
|
|
|
```rust
|
|
use serde::{Deserialize, Serialize};
|
|
|
|
#[derive(Debug, PartialEq, Serialize, Deserialize)]
|
|
struct Config {
|
|
name: String,
|
|
enabled: bool,
|
|
retries: i64,
|
|
}
|
|
|
|
fn main() -> wson::Result<()> {
|
|
let value = Config {
|
|
name: "worker".to_string(),
|
|
enabled: true,
|
|
retries: 3,
|
|
};
|
|
|
|
let text = wson::to_string(&value)?;
|
|
assert_eq!(text, r#"{"enabled":true,"name":"worker","retries":3}"#);
|
|
let decoded: Config = wson::from_str(&text)?;
|
|
assert_eq!(decoded, value);
|
|
|
|
let bytes = wson::to_vec(&value)?;
|
|
let decoded: Config = wson::from_slice(&bytes)?;
|
|
assert_eq!(decoded, value);
|
|
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
## References and cycles
|
|
|
|
Serde's data model is acyclic, so cyclic/shared WSON values use the graph API:
|
|
|
|
```rust
|
|
use wson::{Config, Node};
|
|
|
|
fn main() -> wson::Result<()> {
|
|
let cfg = Config {
|
|
serialize_references: true,
|
|
..Config::default()
|
|
};
|
|
|
|
let graph = wson::text::parse_str("(0){\"child\":$0,\"id\":25}", &cfg)?;
|
|
let root = graph.root();
|
|
let child = match graph.node(root) {
|
|
Node::Object(entries) => *entries.get("child").unwrap(),
|
|
_ => panic!("expected object"),
|
|
};
|
|
assert_eq!(root, child);
|
|
|
|
let text = wson::text::dump_graph(&graph, &cfg)?;
|
|
let jbon = wson::binary::dump_graph(&graph, &cfg)?;
|
|
println!("{text} ({} JBON bytes)", jbon.len());
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
## Compatibility notes
|
|
|
|
- WSON integers are signed 64-bit. `u64` values above `i64::MAX` fail to serialize.
|
|
- WSON floats are `f64`. Text output uses Java `Double.toString`-style formatting.
|
|
- The text parser intentionally mirrors the Java parser's leniency: commas/colons are not strictly validated, and unknown characters are skipped.
|
|
- The parser enforces `Config::max_depth`; dumpers do not limit depth, but cyclic graphs require `serialize_references`.
|
|
- Object keys are sorted by default to match the Java default `TreeMap` object implementation.
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
cargo run --example serde_text
|
|
cargo run --example serde_jbon
|
|
cargo run --example graph_references
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
cargo fmt --check
|
|
cargo clippy --all-targets -- -D warnings
|
|
cargo test
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|