Extensible data notations based on Cirru syntax
cargo add cirru_edn
Basic parsing and formatting:
use cirru_edn::Edn;
cirru_edn::parse("[] 1 2 true"); // Result<Edn, String>
cirru_edn::format(data, /* use_inline */ true); // Result<String, String>.
Cirru EDN provides seamless integration with serde, allowing you to easily convert between Rust structs and EDN data with efficient direct serialization and deserialization.
An important feature of this implementation is the semantic distinction between struct fields and map keys:
- Struct fields use
Tag
(:field_name
) - representing named constants and structured identifiers - Map keys use
String
("key"
) - representing arbitrary string data
This design preserves the intended meaning of different data elements in EDN format.
use cirru_edn::{to_edn, from_edn};
use serde::{Serialize, Deserialize};
use std::collections::HashMap;
#[derive(Serialize, Deserialize, Debug, PartialEq)]
struct Person {
name: String,
age: u32,
email: Option<String>,
tags: Vec<String>,
metadata: HashMap<String, String>, // Map keys will be Strings
}
let person = Person {
name: "Alice".to_string(),
age: 30,
email: Some("alice@example.com".to_string()),
tags: vec!["developer".to_string(), "rust".to_string()],
metadata: [("role".to_string(), "senior".to_string())].into_iter().collect(),
};
// Convert struct to Edn
let edn_value = to_edn(&person).unwrap();
println!("EDN: {}", edn_value);
// Output: {:name "Alice", :age 30, :email "alice@example.com", :tags ["developer", "rust"], :metadata {"role" "senior"}}
// ^^^^^ Tag ^^^^^^ String
// Convert Edn back to struct
let reconstructed: Person = from_edn(edn_value).unwrap();
assert_eq!(person, reconstructed);
- Primitive types:
bool
,i32
,i64
,u32
,u64
,f32
,f64
,String
- Container types:
Vec<T>
,HashMap<K, V>
,HashSet<T>
- Optional types:
Option<T>
(maps toEdn::Nil
or the actual value) - Nested structures: Arbitrarily deep nested structs
You can also manually construct Edn data and then deserialize it to structs. Remember to use Tags for struct field keys:
use cirru_edn::{Edn, EdnTag, EdnMapView, from_edn};
use std::collections::HashMap;
// Construct EDN manually with proper key types
let mut map = HashMap::new();
map.insert(Edn::Tag(EdnTag::new("name")), "Bob".into()); // Tag for struct field
map.insert(Edn::Tag(EdnTag::new("age")), Edn::Number(25.0)); // Tag for struct field
map.insert(Edn::Tag(EdnTag::new("email")), Edn::Nil); // Tag for struct field
map.insert(Edn::Tag(EdnTag::new("tags")), vec!["junior".to_string(), "javascript".to_string()].into());
// For metadata HashMap, use String keys
let mut metadata_map = HashMap::new();
metadata_map.insert(Edn::Str("department".into()), Edn::Str("engineering".into())); // String for map key
map.insert(Edn::Tag(EdnTag::new("metadata")), Edn::Map(EdnMapView(metadata_map)));
let edn_data = Edn::Map(EdnMapView(map));
let person: Person = from_edn(edn_data).unwrap();
println!("{:?}", person);
When deserialization fails (e.g., missing required fields or type mismatches), descriptive error messages are returned:
let incomplete_edn = Edn::map_from_iter([
("name".into(), "Invalid".into()),
// Missing required age field
]);
match from_edn::<Person>(incomplete_edn) {
Ok(person) => println!("Success: {:?}", person),
Err(e) => println!("Error: {}", e), // Error: missing field `age`
}
See examples/serde_demo.rs
for more complex nested structures and usage patterns.
Cirru EDN supports Record types with named tags, which can be deserialized to Rust structs. During deserialization, the record name is ignored since Rust structs don't expose their type names at runtime:
use cirru_edn::{Edn, EdnRecordView, EdnTag, from_edn};
// Create a Record with a named type
let person_record = Edn::Record(EdnRecordView {
tag: EdnTag::new("PersonRecord"), // This name will be ignored during deserialization
pairs: vec![
(EdnTag::new("name"), "Frank".into()),
(EdnTag::new("age"), Edn::Number(42.0)),
(EdnTag::new("email"), "frank@example.com".into()),
],
});
// Deserialize Record to struct (ignoring the record name)
let person: Person = from_edn(person_record).unwrap();
println!("{:?}", person);
// Note: When serializing structs back to EDN, they become Maps, not Records
// since Rust doesn't provide struct names at runtime
let edn_back = to_edn(&person).unwrap();
// This will be a Map, not a Record
This feature allows interoperability between EDN data containing Records and Rust structs, with the semantic understanding that record names are metadata that may be lost during round-trip conversion.
- Some special Edn types (like
Quote
,AnyRef
) cannot be serialized - Maps with complex keys will use their string representation when serializing structs
- Record names are ignored during deserialization and structs serialize to Maps, not Records
mixed data:
{} (:a 1.0)
:b $ [] 2.0 3.0 4.0
:c $ {} (:d 4.0)
:e true
:f :g
:h $ {} (|a 1.0)
|b true
{}
:b $ [] 2 3 4
:a 1
:c $ {}
:h $ {} (|b true) (|a 1)
:f :g
:e true
:d 4
for top-level literals, need to use do
expression:
do nil
do true
do false
do 1
do -1.1
quoted code:
do 'a
quote (a b)
tags(previously called "keyword")
do :a
string syntax, note it's using prefixed syntax of |
:
do |a
string with special characters:
do \"|a b\"
nested list:
[] 1 2 $ [] 3
#{} ([] 3) 1
tuple, or tagged union, actually very limitted due to Calcit semantics:
:: :a
:: :b 1
extra values can be added to tuple since 0.3
:
:: :a 1 |extra :l
a record, notice that now it's all using tags:
%{} :Demo (:a 1)
:b 2
:c $ [] 1 2 3
extra format for holding buffer, which is internally Vec<u8>
:
buf 00 01 f1 11
atom, which translates to a reference to a value:
atom 1
MIT