add README with high-level usage examples

2 files changed, 94 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d0a2811
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# kdl-schema
+
+[KDL Schema](https://github.com/kdl-org/kdl/blob/1.0.0/SCHEMA-SPEC.md) types and parsing.
+
+## examples
+
+### building a schema
+
+```rust
+use kdl_schema::*;
+let schema = Schema {
+    document: Document {
+        info: Info {
+            title: vec![TextValue {
+                text: "Sample Schema".to_string(),
+                lang: Some("en".to_string()),
+            }],
+            ..Info::default()
+        },
+        nodes: vec![Node {
+            name: Some("name".to_string()),
+            values: vec![Value {
+                validations: vec![Validation::Type("string".to_string())],
+                ..Value::default()
+            }],
+            ..Node::default()
+        }]
+    }
+};
+println!("{:?}", schema);
+```
+
+### parsing a schema KDL
+
+```rust
+#[cfg(feature = "parse-knuffel")] {
+    let schema_kdl = r#"
+document {
+    info {
+        title "Sample Schema" lang="en"
+        description "An example schema" lang="en"
+        author "boringcactus"
+    }
+    node "name" {
+        value {
+            type "string"
+        }
+    }
+    node "age" {
+        value {
+            type "number"
+        }
+    }
+}
+"#;
+    let _matching_document = r#"
+name "Joe"
+age 69
+"#;
+    let schema = kdl_schema::Schema::parse(schema_kdl).unwrap();
+    assert_eq!(schema.document.info.title[0].text, "Sample Schema");
+}
+```
+
+### referencing the schema schema
+
+```rust
+assert_eq!(kdl_schema::SCHEMA_SCHEMA.document.info.title[0].text, "KDL Schema");
+```
+
+## cargo features
+
+- `parse-knuffel` - expose `Schema::parse`, powered by [the `knuffel` crate](https://crates.io/crates/knuffel)
+
+## conditions blocking version 1.0.0
+
+- types actually match the schema (currently I'm omitting several things because the schema schema doesn't use them)
+- ergonomic builder API to define a schema in Rust in a non-ugly way
+- can generate KDL
+- can choose kdl or knuffel as parser
+
+## license
+
+[Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0).
diff --git a/src/lib.rs b/src/lib.rs
index 97dbce4..c724687 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![warn(clippy::pedantic, clippy::cargo)]
 
 #[cfg(feature = "parse-knuffel")]
@@ -17,6 +18,15 @@ pub struct Schema {
     pub document: Document,
 }
 
+#[cfg(feature = "parse-knuffel")]
+impl Schema {
+    pub fn parse(
+        schema_kdl: &str,
+    ) -> Result<Self, knuffel::Error<impl knuffel::traits::ErrorSpan>> {
+        knuffel::parse("<Schema::parse argument>", schema_kdl)
+    }
+}
+
 #[derive(Debug, PartialEq, Eq, Default)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub struct Document {