aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMelody Horn <melody@boringcactus.com>2022-03-27 00:19:57 -0600
committerMelody Horn <melody@boringcactus.com>2022-03-27 00:19:57 -0600
commit57e7a3513a7d247923288e05f9dd0cbc8ef288fd (patch)
tree59ceb7f74d61560f1b600158eed9fc450c7a4602
parent8130a49f045764a200082e5c296eae7a9d4b4e37 (diff)
downloadkdl-schema-57e7a3513a7d247923288e05f9dd0cbc8ef288fd.tar.gz
kdl-schema-57e7a3513a7d247923288e05f9dd0cbc8ef288fd.zip
add README with high-level usage examples
-rw-r--r--README.md84
-rw-r--r--src/lib.rs10
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 {