Merge pull request #85 from quartiq/release/v0.4.0

Preparing for miniconf release 0.4.0

CHANGELOG.md

@@ -6,6 +6,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2022-05-11
+
 ### Added
 * Added support for custom handling of settings updates.
 * `Option` support added to enable run-time settings tree presence.
@@ -47,7 +49,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Library initially released on crates.io
 
-[Unreleased]: https://github.com/quartiq/miniconf/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/quartiq/miniconf/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/quartiq/miniconf/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/quartiq/miniconf/releases/tag/v0.3.0
 [0.2.0]: https://github.com/quartiq/miniconf/releases/tag/v0.2.0
 [0.1.0]: https://github.com/quartiq/miniconf/releases/tag/v0.1.0

Cargo.toml

@@ -1,6 +1,9 @@
 [package]
 name = "miniconf"
-version = "0.3.0"
+
+# Don't forget to change `derive_miniconf`'s version as well.
+version = "0.4.0"
+
 authors = ["James Irwin <irwineffect@gmail.com>", "Ryan Summers <ryan.summers@vertigo-designs.com"]
 edition = "2018"
 license = "MIT"
@@ -10,7 +13,7 @@ keywords = ["settings", "embedded", "no_std", "configuration", "mqtt"]
 categories = ["no-std", "config", "embedded", "parsing"]
 
 [dependencies]
-derive_miniconf = { path = "derive_miniconf" , version = "0.3" }
+derive_miniconf = { path = "derive_miniconf" , version = "0.4" }
 serde-json-core = "0.4.0"
 serde = { version = "1.0.120", features = ["derive"], default-features = false }
 log = "0.4"

README.md

@@ -3,58 +3,25 @@
 [![QUARTIQ Matrix Chat](https://img.shields.io/matrix/quartiq:matrix.org)](https://matrix.to/#/#quartiq:matrix.org)
 ![Continuous Integration](https://github.com/vertigo-designs/miniconf/workflows/Continuous%20Integration/badge.svg)
 
-MiniConf is a `no_std` minimal run-time settings configuration tool designed to be run on top of
+Miniconf is a `no_std` minimal run-time settings configuration tool designed to be run on top of
 any communication means. It was originally designed to work with MQTT clients and provides a default
 implementation using [minimq](https://github.com/quartiq/minimq) as the MQTT client.
 
-# Design
+Check out the [documentation](https://docs.rs/miniconf/latest/miniconf/)  for examples and detailed
+information.
 
-Miniconf provides an easy-to-work-with API for quickly adding runtime-configured settings to any
-embedded project. This allows any internet-connected device to quickly bring up configuration
-interfaces with minimal implementation in the end-user application.
+# Features
 
-MiniConf provides a `Miniconf` derive macro for creating a settings structure, e.g.:
-```rust
-use miniconf::Miniconf;
+Miniconf provides simple tools to bring run-time configuration up on any project. Any device that
+can send and receive data can leverage Miniconf to provide run-time configuration utilities.
 
-#[derive(Miniconf)]
-struct NestedSettings {
-    inner: f32,
-}
+This crate provides a Derive macro is provided to automatically map Rust structures into a key-value
+lookup tool, where keys use a string-based, path-like syntax to access and modify structure members.
 
-#[derive(Miniconf)]
-struct MySettings {
-    initial_value: u32,
-    internal: NestedSettings,
-}
+Miniconf also provides an MQTT client and Python utility to quickly bring IoT and remote
+configuration to your project. After running programming your device, settings updates are easily
+accomplished using Python:
+```sh
+# Set the `sample_rate_hz` value of device with identifier `quartiq/example_device` to `10`.
+python -m miniconf quartiq/example_device sample_rate_hz=10
 ```
-
-# Settings Paths
-
-A setting value must be configured via a specific path. Paths take the form of variable names
-separated by slashes - this design follows typical MQTT topic design semantics. For example, with
-the following `Settings` structure:
-```rust
-#[derive(Miniconf)]
-struct Data {
-    inner: f32,
-}
-
-#[derive(Miniconf)]
-struct Settings {
-    initial_value: u32,
-    internal: Data,
-}
-```
-
-We can access `Data::inner` with the path `internal/inner`.
-
-Settings may only be updated at the terminal node. That is, you cannot configure
-`<device-id>/settings/internal` directly. If this is desired, instead derive `MiniconfAtomic` on the
-`struct Data` definition. In this way, all members of `struct Data` must be updated simultaneously.
-
-# Settings Values
-
-MiniConf relies on using [`serde`](https://github.com/serde-rs/serde) for defining a
-de/serialization method for settings. Currently, MiniConf only supports serde-json de/serialization
-formats, although more formats may be supported in the future.

derive_miniconf/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "derive_miniconf"
-version = "0.3.0"
+version = "0.4.0"
 authors = ["James Irwin <irwineffect@gmail.com>", "Ryan Summers <ryan.summers@vertigo-designs.com"]
 edition = "2018"
 license = "MIT"

src/lib.rs

@@ -12,6 +12,14 @@
 //! With the derive macro, field values can be easily retrieved or modified using a run-time
 //! string.
 //!
+//! ### Supported Protocols
+//!
+//! Miniconf is designed to be protocol-agnostic. Any means that you have of receiving input from
+//! some external source can be used to acquire paths and values for updating settings.
+//!
+//! There is also an [MQTT-based client](MqttClient) provided to manage settings via the [MQTT
+//! protocol](https://mqtt.org) and JSON.
+//!
 //! ### Example
 //! ```
 //! use miniconf::{Miniconf, MiniconfAtomic};
@@ -45,13 +53,40 @@
 //! // Serialize the current sample rate into the provided buffer.
 //! let mut buffer = [0u8; 256];
 //! let len = settings.get("sample_rate", &mut buffer).unwrap();
-//! // `sample_rate`'s serialized value now exists in `buffer[..len]`.
+//!
+//! assert_eq!(&buffer[..len], b"350");
 //! ```
 //!
 //! ## Features
 //! Miniconf supports an MQTT-based client for configuring and managing run-time settings via MQTT.
 //! To enable this feature, enable the `mqtt-client` feature.
 //!
+//! ```no_run
+//! #[derive(miniconf::Miniconf, Default, Clone, Debug)]
+//! struct Settings {
+//!     forward: f32,
+//! }
+//!
+//! // Construct the MQTT client.
+//! let mut client: miniconf::MqttClient<_, _, _, 256> = miniconf::MqttClient::new(
+//!     std_embedded_nal::Stack::default(),
+//!     "example-device",
+//!     "quartiq/miniconf-sample",
+//!     "127.0.0.1".parse().unwrap(),
+//!     std_embedded_time::StandardClock::default(),
+//!     Settings::default(),
+//! )
+//! .unwrap();
+//!
+//! loop {
+//!     // Continually process client updates to detect settings changes.
+//!     if client.update().unwrap() {
+//!         println!("Settings updated: {:?}", client.settings());
+//!     }
+//! }
+//!
+//! ```
+//!
 //! ### Path iteration
 //!
 //! Miniconf also allows iteration over all settings paths:
@@ -72,14 +107,6 @@
 //! }
 //! ```
 //!
-//! ## Supported Protocols
-//!
-//! Miniconf is designed to be protocol-agnostic. Any means that you have of receiving input from
-//! some external source can be used to acquire paths and values for updating settings.
-//!
-//! While Miniconf is platform agnostic, there is an [MQTT-based client](MqttClient) provided to
-//! manage settings via the [MQTT protocol](https://mqtt.org).
-//!
 //! ## Limitations
 //!
 //! Minconf cannot be used with some of Rust's more complex types. Some unsupported types:
@@ -90,9 +117,11 @@
 mod mqtt_client;
 
 mod array;
-pub mod iter;
 mod option;
 
+/// Provides iteration utilities over [Miniconf] structures.
+pub mod iter;
+
 #[cfg(feature = "mqtt-client")]
 pub use mqtt_client::MqttClient;
 
@@ -194,6 +223,7 @@ pub struct MiniconfMetadata {
     pub max_depth: usize,
 }
 
+/// Derive-able trait for structures that can be mutated using serialized paths and values.
 pub trait Miniconf {
     /// Update settings directly from a string path and data.
     ///