example plus programmers information

doc/index.rst

@@ -20,6 +20,7 @@ Contents:
     :maxdepth: 2
 
     user
+    programmer
 
 .. _Yaml: http://yaml.org
 

doc/programmer.rst

@@ -0,0 +1,44 @@
+
+================
+Programmer Guide
+================
+
+As a programmer you are looking for source code.
+You found it, here it is.
+
+.. literalinclude:: ../examples/simple.rs
+    :language: rust
+
+
+Key link
+========
+
+The key link between configuration file
+and the executable programm that you are writen
+is the configuration ``struct``.
+
+In the demo source code is that struct named *Config*
+and is *cfg* a variable of type Config.
+
+
+config.yaml
+===========
+
+Nothing of ``Config`` or ``cfg`` needs to be in the YAML.
+But the field names **must**.
+
+Here the *.yaml* that goes with the above example source code.
+
+
+.. literalinclude:: ../examples/config.yaml
+    :language: yaml
+
+
+See also
+========
+
+The documentation of `serde <https://serde.rs/>`_.
+
+Our ``examples`` directory.
+
+`Reverse dependencies <https://crates.io/crates/quire/reverse_dependencies>`_.

examples/README.text

@@ -0,0 +1,10 @@
+
+Run
+  cargo build --examples
+anywhere to get examples been compiled.
+
+For
+  cargo run --example simple
+be in the top directory of the project.
+That is for having the correct start point
+to get path to config.yaml right.

examples/config.yaml

@@ -0,0 +1,8 @@
+#
+---
+item1:  foo
+# comment
+item2:  bar
+_item3:  underscore used to comment out a keyword
+...
+# l l

examples/simple.rs

@@ -0,0 +1,31 @@
+extern crate quire;
+#[macro_use] extern crate serde_derive;
+use quire::{parse_config, Options};
+use quire::validate::{Structure, Scalar};
+
+#[derive(Deserialize)]
+#[allow(dead_code)]
+struct Config {
+    item1: String,
+    item2: Option<String>,
+}
+
+fn validator() -> Structure<'static> {
+    Structure::new()
+    .member("item1", Scalar::new())
+    .member("item2", Scalar::new().optional())
+}
+
+fn work(cfg: &Config) {
+    println!("item1 is {}.", cfg.item1);
+    //intln!("item2 is {}.", cfg.item2);
+    // hey, this is just demonstration code ...
+}
+
+fn main() {
+    let cfg: Config;
+    cfg = parse_config("examples/config.yaml",
+                       &validator(), &Options::default())
+        .expect("valid config");
+    work(&cfg)
+}