smart_config/_docs/
derive_examples.rs

1//! # Derive macro examples
2//!
3//! Various examples how to use [`DescribeConfig`](macro@crate::DescribeConfig) and other derive macros
4//! from the library.
5//!
6//! # Basic usage
7//!
8//! Shows how to use the macros with nested and flattened sub-configs, enum configs etc.
9//!
10//! ```
11//! # use std::{collections::HashSet, num::NonZeroUsize, time::Duration};
12//! # use smart_config::{DescribeConfig, DeserializeConfig};
13//! use smart_config::metadata::TimeUnit;
14//!
15//! #[derive(DescribeConfig, DeserializeConfig)]
16//! struct TestConfig {
17//!     /// Doc comments are parsed as a description.
18//!     #[config(default_t = 3)]
19//!     int: u32,
20//!     #[config(default)] // multiple `config` attrs are supported
21//!     #[config(rename = "str", alias = "string")]
22//!     renamed: String,
23//!     /// Nested sub-config. E.g., the tag will be read from path `nested.version`.
24//!     #[config(nest)]
25//!     nested: NestedConfig,
26//!     /// Flattened sub-config. E.g., `array` param will be read from `array`, not `flat.array`.
27//!     #[config(flatten)]
28//!     flat: FlattenedConfig,
29//! }
30//!
31//! #[derive(DescribeConfig, DeserializeConfig)]
32//! #[config(tag = "version", rename_all = "snake_case", derive(Default))]
33//! enum NestedConfig {
34//!     #[config(default)]
35//!     V0,
36//!     #[config(alias = "latest")]
37//!     V1 {
38//!         /// Param with a custom deserializer. In this case, it will deserialize
39//!         /// a duration from a number with milliseconds unit of measurement.
40//!         #[config(default_t = Duration::from_millis(50), with = TimeUnit::Millis)]
41//!         latency_ms: Duration,
42//!         /// `Vec`s, sets and other containers are supported out of the box.
43//!         set: HashSet<NonZeroUsize>,
44//!     },
45//! }
46//!
47//! #[derive(DescribeConfig, DeserializeConfig)]
48//! struct FlattenedConfig {
49//!     #[config(default = FlattenedConfig::default_array)]
50//!     array: [f32; 2],
51//! }
52//!
53//! impl FlattenedConfig {
54//!     const fn default_array() -> [f32; 2] { [1.0, 2.0] }
55//! }
56//! ```
57//!
58//! # Deriving `ExampleConfig`
59//!
60//! ```
61//! # use std::collections::HashSet;
62//! # use smart_config::{DescribeConfig, ExampleConfig, SerializerOptions};
63//! #[derive(DescribeConfig, ExampleConfig)]
64//! struct TestConfig {
65//!     /// Required param that still has an example value.
66//!     #[config(example = 42)]
67//!     required: u32,
68//!     optional: Option<String>,
69//!     #[config(default_t = true)]
70//!     with_default: bool,
71//!     #[config(default, example = vec![5, 8])]
72//!     values: Vec<u32>,
73//!     #[config(nest)]
74//!     nested: NestedConfig,
75//! }
76//!
77//! #[derive(DescribeConfig, ExampleConfig)]
78//! struct NestedConfig {
79//!     #[config(default, example = ["eth_call".into()].into())]
80//!     methods: HashSet<String>,
81//! }
82//!
83//! let example: TestConfig = TestConfig::example_config();
84//! let json = SerializerOptions::default().serialize(&example);
85//! assert_eq!(
86//!     serde_json::Value::from(json),
87//!     serde_json::json!({
88//!         "required": 42,
89//!         "optional": null,
90//!         "with_default": true,
91//!         "values": [5, 8],
92//!         "nested": {
93//!             "methods": ["eth_call"],
94//!         },
95//!     })
96//! );
97//! ```
98//!
99//! # Advanced features
100//!
101//! Demonstrates some advanced library features:
102//!
103//! - [Parameter validation](crate::validation)
104//! - [Fallback values](crate::fallback)
105//! - Complex deserializers: [`Delimited`](crate::de::Delimited), [`NamedEntries`](crate::de::NamedEntries)
106//!   and [`DelimitedEntries`](crate::de::DelimitedEntries)
107//! - Use or [regexes](crate::pat) as delimiters and validations
108//! - Deserialization of values [with units](crate::de::WithUnit), and the fixed-unit alternative
109//! - [Deprecated aliases](super::derive_ref#deprecated) and the use of paths
110//! - [Secret values](super::derive_ref#secret).
111//!
112//! ```
113#![doc = include_str!("../../tests/code_samples/test_config.rs")]
114//! ```
115//!
116//! ## Matching YAML configuration
117//!
118//! ```yaml
119#![doc = include_str!("../../tests/code_samples/test.yml")]
120//! ```
121//!
122//! ## Matching env variables
123//!
124//! Assumes the `APP_` prefix for env vars.
125//!
126//! ```shell
127#![doc = include_str!("../../tests/code_samples/test.env")]
128//! ```
129//!
130//! # See also
131//!
132//! - [Derive macro reference](super::derive_ref)
133//! - [Combining config sources](super::sources)
smart_config/_docs/derive_examples.rs

smart_config/_docs/
derive_examples.rs
