derpscfg 0.8.0

//! # Derive documentation
//!
//! Derpscfg can currently derive decoding for regular struct types with named
//! fields and simple enums (without fields). There is currently no support for
//! tuples, newtypes, or more complex enums.
//!
//! Here is a complete minimal example:
//!
//! ```rust
//! use derpscfg::prelude::*;
//!
//! #[derive(Debug, Derpscfg)]
//! struct FooBar {
//!     foo: String,
//!     baz: String,
//! }
//!
//! static SCFG_DOC: &str = r#"
//! foo foovalue
//! baz bazvalue
//! "#;
//!
//! let foobar: FooBar = derpscfg::parse(SCFG_DOC).unwrap();
//! println!("{foobar:?}");
//!
//! ```
//!
//! All following examples will only show how the struct definition(s) and the
//! scfg document can be refined.
//!
//! Often, scfg documents are structured to have a single toplevel node, for
//! example:
//!
//! ```scfg
//! config {
//!     foo foovalue
//!     baz bazvalue
//! }
//! ```
//!
//! There is no special mechanism or attribute to accomplish this. Instead, a
//! simple wrapper struct has to be used:
//!
//! ```rust
//! # use derpscfg::prelude::*;
//! #[derive(Debug, Derpscfg)]
//! struct FooBar {
//!     foo: String,
//!     baz: String,
//! }
//!
//! #[derive(Debug, Derpscfg)]
//! struct Config {
//!     config: FooBar,
//! }
//! ```
//!
//! ## Field names
//!
//! Type names are irrelevant for decoding, but field names are important. The
//! field names in the scfg document have to reflect the struct field names.
//! There is only one exception: an underscore in a struct field name can be
//! represented by either an underscore or a dash in the scfg document. Both
//! will work, but usage has to be consistent. For example:
//!
//! ```rust
//! # use derpscfg::prelude::*;
//! #[derive(Debug, Derpscfg)]
//! struct FooBar {
//!     foo_bar: String,
//!     baz: String,
//! }
//!
//! #[derive(Debug, Derpscfg)]
//! struct Config {
//!     config: FooBar,
//! }
//! ```
//!
//! can parse the following document:
//!
//! ```scfg
//! config {
//!     foo-bar foovalue
//!     baz bazvalue
//! }
//! ```
//!
//! Field names can also be overridden, using the `name` annotation. Note that
//! this will remove all ambiguity of hyphens or dashes, only the exact provided
//! value will work.
//!
//! For example:
//!
//! ```rust
//! # use derpscfg::prelude::*;
//! #[derive(Debug, Derpscfg)]
//! struct FooBar {
//!     #[scfg(name="barfoo")]
//!     foo_bar: String,
//!     baz: String,
//! }
//!
//! #[derive(Debug, Derpscfg)]
//! struct Config {
//!     config: FooBar,
//! }
//! ```
//!
//! can parse the following document:
//!
//! ```scfg
//! config {
//!     barfoo foovalue
//!     baz bazvalue
//! }
//! ```
//!
//! ## Field types and cardinality
//!
//! Fields can be one of most standard library types that implement
//! [`FromStr`](std::str::FromStr). A full list is available in the
//! [docs](crate::DecodeScalar#foreign-impls). Such fields _must_ be present in
//! the parsed scfg document. Fields can also be an [`Option`] of said types, in
//! which case they can be omitted in the scfg document.
//!
//! Collections are also supported. If a field is either a [`Vec`],
//! [`VecDeque`][std::collections::VecDeque],
//! [`LinkedList`](std::collections::LinkedList),
//! [`BTreeSet`](std::collections::BTreeSet), or
//! [`HashSet`](std::collections::HashSet) of a supported field type, then the
//! respective directive can show up zero or more times. There are currently no
//! means to restrict cardinality on the list and set types. The set types will
//! silently discard duplicate values.
//!
//! The following structs for example:
//!
//! ```rust
//! # use derpscfg::prelude::*;
//! #[derive(Debug, Derpscfg)]
//! struct FooBar {
//!     foo_bar: Option<String>,
//!     baz: Vec<String>,
//! }
//!
//! #[derive(Debug, Derpscfg)]
//! struct Config {
//!     config: FooBar,
//! }
//! ```
//!
//! would accept the following document:
//!
//! ```scfg
//! config {
//! # foo-bar is optional, baz has cardinality * (zero or more), so empty node
//! # satisfies all requirements
//! }
//! ```
//!
//! but also:
//!
//! ```scfg
//! config {
//!     baz bazvalue1 bazvalue2 bazvalue3
//! }
//! ```
//!
//! Note that a list of scalars can come from either repeated directives, or a
//! directive with multiple parameters, hence the following document is
//! equivalent to the one above:
//!
//! ```scfg
//! config {
//!     baz bazvalue1
//!     baz bazvalue2
//!     baz bazvalue3
//! }
//! ```
//!
//! Last, but not least, maps are supported as well. Currently, keys must always
//! be strings, values can be any decodable type. If a field is a
//! [`BTreeSet`](std::collections::btree_map::BTreeMap) or a
//! [`HashMap`](std::collections::hash_map::HashMap), the corresponding
//! directive can again occur zero or more times. The directive _must_ have at
//! least one parameter, which is consumed as the map key (i.e. removed) before
//! decoding the value.
//!
//! The following structs for example:
//!
//! ```rust
//! # use derpscfg::prelude::*;
//! # use std::collections::hash_map::HashMap;
//! #[derive(Debug, Derpscfg)]
//! struct FooBar {
//!     baz: HashMap<String, u64>,
//! }
//!
//! #[derive(Debug, Derpscfg)]
//! struct Config {
//!     config: FooBar,
//! }
//! ```
//!
//! would decode the following document:
//!
//! ```scfg
//! config {
//!     baz key1 23
//!     baz key2 5
//!     baz key3 42
//! }
//! ```
//!
//! The resulting map would have the keys `"key1"`, `"key2"`, `"key3"` and the
//! values `23`, `5`, `42` respectively. Unlike sets, maps cause an error if
//! they encounter duplicate keys, as their occurrence usually hints at semantic
//! issues.
//!
//! If the `derpscfg` crate is compiled with the `preserve_order` feature, it
//! re-exports the [`IndexSet`][iset] and [`IndexMap`][imap] types that it uses
//! internally. Decoding is supported for them as well (but you must use the
//! re-exported type).
//!
//! [iset]: https://docs.rs/indexmap/latest/indexmap/set/struct.IndexSet.html
//! [imap]: https://docs.rs/indexmap/latest/indexmap/map/struct.IndexMap.html
//!
//! ## Parameters
//!
//! Fields annotated with `#[scfg(param)]` are taken from a directive's
//! parameters in order of declaration. The struct field names are irrelevant in
//! this case. Be careful with cardinality: a `Vec` will always take _all_
//! available params, so there can only be one, and it must be the last field
//! from parameters.
//!
//! Example:
//!
//! ```rust
//! # use derpscfg::prelude::*;
//! #[derive(Debug, Derpscfg)]
//! struct FooBar {
//!     #[scfg(param)]
//!     cfgtype: String,
//!     foo_bar: String,
//!     baz: String,
//! }
//!
//! #[derive(Debug, Derpscfg)]
//! struct Config {
//!     config: FooBar,
//! }
//! ```
//!
//! will parse the following:
//!
//! ```scfg
//! config debug {
//!     foo-bar foovalue
//!     baz bazvalue
//! }
//! ```
//!
//! where `FooBar.cfgtype` will be `"debug"`.
//!
//! The [`derpscfg::parse()`](./fn.parse.html) function can **only be used on
//! types that _do not_ declare any fields with `param`**, as the toplevel
//! [`Scfg`](crate::Scfg) element does not have any.
//!
//! ## Enums
//!
//! The required glue for simple enums can also be derived. The enum variants
//! must not have any fields. The last example above could be refined
//! accordingly:
//!
//! ```rust
//! # use derpscfg::prelude::*;
//! #[derive(Debug, Derpscfg)]
//! enum CfgType {
//!     Debug,
//!     Release,
//!     ReleaseOptimized,
//! }
//!
//! #[derive(Debug, Derpscfg)]
//! struct FooBar {
//!     #[scfg(param)]
//!     cfgtype: String,
//!     foo_bar: String,
//!     baz: String,
//! }
//!
//! #[derive(Debug, Derpscfg)]
//! struct Config {
//!     config: FooBar,
//! }
//! ```
//!
//! This will (again) parse the following:
//!
//! ```scfg
//! config debug {
//!     foo-bar foovalue
//!     baz bazvalue
//! }
//! ```
//!
//! but the following would produce an error, as `prod` cannot be mapped to a
//! variant of `CfgType`:
//!
//! ```scfg
//! config prod {
//!     foo-bar foovalue
//!     baz bazvalue
//! }
//! ```
//!
//! Enum values can be written in lower, camel or snake case, so valid values
//! would be `Debug`, `Release`, `ReleaseOptimized`, `debug`, `release`,
//! `releaseoptimized`, or `release_optimized`. However, consistency matters.
//!
//! ## Generic key-value maps
//!
//! If you need the map-style genericity of scfg in parts of your data you can
//! parse a field to a [`Directive`](crate::Directive) (or `Option`/`Vec`/etc.
//! thereof):
//!
//! ```rust
//! # use derpscfg::prelude::*;
//! #[derive(Debug, Derpscfg)]
//! struct FooBar {
//!     foo_bar: String,
//!     baz: derpscfg::Directive,
//! }
//!
//! #[derive(Debug, Derpscfg)]
//! struct Config {
//!     config: FooBar,
//! }
//! ```
//!
//! This allows arbitrary data for `baz`, such as:
//!
//! ```scfg
//! config {
//!     foo-bar value
//!     baz takes arbitrary params {
//!         and arbitrary
//!         nested {
//!             child nodes
//!         }
//!     }
//! }
//! ```
//!
//! This defers validation to the application code, but can be useful to let
//! users supply arbitrary key-value-pairs or other semi-structured data.
//!
//! ## Default values
//!
//! Fields with a cardinality of one (i.e. that are not `Option`/`Vec`/etc.) can
//! be declared to have a default value if not present. Annotating a field with
//! `#[scfg(default)]` will use the type's default value. The type must
//! implement [`Default`] for this. If the type does not implement [`Default`],
//! or a different default value is desired, a default expression can be
//! provided. A field annotated for example with
//! `#[scfg(default=String::from("default"))]` would default to the string
//! `"default"` as opposed to the empty string (which is the String type's
//! default value).
//!
//! For example:
//!
//! ```rust
//! # use derpscfg::prelude::*;
//! #[derive(Debug, Derpscfg)]
//! struct FooBar {
//!     #[scfg(default)]
//!     foo: String,
//!     #[scfg(default=String::from("bazvalue"))]
//!     baz: String,
//! }
//!
//! #[derive(Debug, Derpscfg)]
//! struct Config {
//!     config: FooBar,
//! }
//! ```
//!
//! would parse an empty document:
//!
//! ```scfg
//! config {
//! }
//! ```
//!
//! and end up with `foo` being the empty string and `baz` being `"bazvalue"`.
//!
//! ## Skipping fields
//!
//! Fields annotated with `#[scfg(skip)]` are excluded from deserialization.
//! However, since a skipped field still has to be initialized, either its type
//! has to implement [`Default`] or a `default` annotation providing a default
//! value (see above) has to be provided.
//!
//! For example:
//!
//! ```rust
//! # use derpscfg::prelude::*;
//! #[derive(Debug, Derpscfg)]
//! struct FooBar {
//!     #[scfg(default)]
//!     foo: String,
//!     #[scfg(skip,default=String::from("bazvalue"))]
//!     baz: String,
//! }
//!
//! #[derive(Debug, Derpscfg)]
//! struct Config {
//!     config: FooBar,
//! }
//! ```
//!
//! would parse the following document:
//!
//! ```scfg
//! config {
//!     baz "ignored"
//! }
//! ```
//!
//! but the value of `baz` would be `"bazvalue"` (the provided default), because
//! the field is completely skipped during decoding.