Add examples for serde and serde_json.

Fixes #2

Cargo.toml

@@ -12,8 +12,13 @@ license = "MIT/Apache-2.0"
 readme = "README.md"
 
 [features]
+# JSON Canonicalization Scheme (JCS) implementation. 
 canonicalize = [ "ryu-js", "json-number/canonical" ]
+
+# Serialization/Deserialization support using `serde`.
 serde = [ "dep:serde", "json-number/serde" ]
+
+# Compatibility layer with the `serde_json` crate.
 serde_json = [ "dep:serde_json", "json-number/serde_json" ]
 
 [dependencies]
@@ -31,4 +36,12 @@ serde = { version = "1.0", optional = true }
 serde_json = { version = "1.0", optional = true }
 
 [dev-dependencies]
-serde = { version = "1.0", features = [ "derive" ] }
+serde = { version = "1.0", features = [ "derive" ] }
+
+[[example]]
+name = "serde"
+required-features = ["serde"]
+
+[[example]]
+name = "serde_json"
+required-features = ["serde_json"]

examples/serde.rs

@@ -0,0 +1,30 @@
+//! This example shows how to serialize and deserialize `json_syntax::Value`
+//! using the `serde` crate. This will not allow you to attach metadata to each
+//! value fragment (the `M` type will be unit `()`).
+use json_syntax::Print;
+
+#[derive(Debug, PartialEq, serde::Serialize, serde::Deserialize)]
+struct MyType {
+	foo: String,
+	bar: Vec<u32>,
+}
+
+fn main() {
+	// Instantiate our type.
+	let a = MyType {
+		foo: "Hello World!".to_string(),
+		bar: vec![1, 2, 3],
+	};
+
+	// Serialize `a` into a JSON value.
+	let json = json_syntax::to_value(&a).expect("serialization failed");
+
+	// Print the value.
+	println!("{}", json.pretty_print());
+
+	// Deserialize JSON back into `MyType`.
+	let b: MyType = json_syntax::from_value(json).expect("deserialization failed");
+
+	// The round-trip should not change the actual data.
+	assert_eq!(a, b)
+}

examples/serde_json.rs

@@ -0,0 +1,36 @@
+//! This example shows how to convert a `serde_json::Value` into/from a
+//! `json_syntax::Value` using the `serde_json` feature.
+
+fn main() {
+	// First we create a `serde_json` value.
+	let a = serde_json::json!({
+		"foo": 1,
+		"bar": [2, 3]
+	});
+
+	// We convert the `serde_json` value into a `json_syntax` value.
+	let b = json_syntax::Value::from_serde_json(a, |fragment| {
+		// `json_syntax` keeps metadata information attached to every value
+		// fragment, which `serde_json` does not. This is why this closure is
+		// necessary. It is called for every `serde_json` fragment to let you
+		// choose the metadata you want to associate to the fragment.
+		// This is intended to store code mapping information, but you can store
+		// any information. Here we store a text description of the fragment.
+		match fragment {
+			json_syntax::SerdeJsonFragment::Key(key) => {
+				format!("I'm an object key `{key}`")
+			}
+			json_syntax::SerdeJsonFragment::Value(value) => match value {
+				serde_json::Value::Null => "I'm the `null` value".to_string(),
+				serde_json::Value::Bool(b) => format!("I'm the boolean `{b:?}`"),
+				serde_json::Value::Number(n) => format!("I'm the number {n}"),
+				serde_json::Value::String(s) => format!("I'm the string {s:?}"),
+				serde_json::Value::Array(a) => format!("I'm an array of {} elements", a.len()),
+				serde_json::Value::Object(o) => format!("I'm an object of {} entries", o.len()),
+			},
+		}
+	});
+
+	// We convert it back into a `serde_json` value.
+	let _ = json_syntax::Value::into_serde_json(b);
+}