fancy_default/
lib.rs

1//! # `fancy-default`
2//! 
3//! This library provides enhancements to the standard library's `Default` derive macro.
4//! 
5//! ![Crates.io Downloads (recent)](https://img.shields.io/crates/dr/fancy-default?logo=rust&link=https%3A%2F%2Fcrates.io%2Fcrates%2Ffancy-default)
6//! ![Crates.io License](https://img.shields.io/crates/l/fancy-default)
7//! ![Crates.io Version](https://img.shields.io/crates/v/fancy-default)
8//! 
9//! ## Table of Contents
10//! 
11//! - [Generic default value configuration](#generic-default-value-configuration)
12//! - [the `Default` macro](#fancy_defaultderivedefault)
13//! - [the `ConstDefault` macro](#fancy_defaultderiveconstdefault)
14//! - [the `VariantDefault` macro](#fancy_defaultderivevariantdefault)
15//! - [License & MSRV](#msrv)
16//! 
17//! ## Generic default value configuration
18//! 
19//! All default value configurations in this library use the same syntax.
20//! 
21//! - Field configuration:
22//!   - `#[default]`: Calls `core::default::Default` and uses it as the default value.
23//! 
24//!     **Note**: Currently `core::default::Default` is not a constant trait,
25//!     so a default value must be specified when using `ConstDefault`.
26//!   - `#[default = <expr>]`: Use `<expr>` as the default value for this field.
27//! 
28//!     **Note**: `better_default` does not use string literals to parse expressions,
29//!     so you can write expressions with default values directly,
30//!     like: `#[default = "foobar".to_owned()]`.
31//!   - `#[default(expr = <expr>)]`: Same meaning as the previous format.
32//! - Variant configuration(enum only):
33//!   - `#[default]`: Set the variant as the default variant of the enum.  
34//!     This attribute works the same as the standard library's `#[default]`.
35//! 
36//! ## `fancy_default::derive::Default`
37//! 
38//! **Basic Usage:**
39//! 
40//! ```rust
41//! use fancy_default::Default;
42//! 
43//! #[derive(Debug, Default, PartialEq, Eq)]
44//! struct Person {
45//!     #[default(expr = "no-name".to_owned())]
46//!     name: String,
47//!     #[default]
48//!     id: usize,
49//!     #[default(expr = Some("unknown".to_owned()))]
50//!     tag: Option<String>,
51//! }
52//! 
53//! assert_eq!(
54//!     Person::default(),
55//!     Person {
56//!         name: "no-name".to_owned(),
57//!         id: 0,
58//!         tag: Some("unknown".to_owned()),
59//!     }
60//! );
61//! ```
62//! 
63//! ## `fancy_default::derive::ConstDefault`
64//! 
65//! **Basic Usage:**
66//! 
67//! ```rust
68//! // this imports both `fancy_default::derive::ConstDefault`
69//! // and `fancy_default::traits::ConstDefault`.
70//! use fancy_default::ConstDefault;
71//! 
72//! #[derive(Debug, ConstDefault, PartialEq, Eq)]
73//! struct Person<'a> {
74//!     #[default = "no-name"]
75//!     name: &'a str,
76//!     #[default = 0]
77//!     id: usize,
78//!     #[default(expr = Some("unknown"))]
79//!     tag: Option<&'a str>,
80//! }
81//! 
82//! assert_eq!(
83//!     Person::DEFAULT,
84//!     Person {
85//!         name: "no-name",
86//!         id: 0,
87//!         tag: Some("unknown"),
88//!     }
89//! );
90//! ```
91//! 
92//! ## `fancy_default::derive::VariantDefault`
93//! 
94//! Set default values for each variant of the enumeration.This derive macro uses an additional attribute `variant`, to set how the default value are generated.
95//! 
96//! **Config Syntax:**
97//! 
98//! - `#[variant(<config>)]`:
99//!   - `const`/`const = <bool>`: Whether to generate constant default values.
100//!   The corresponding constant name is the UPPER_CASE version of the current enumeration.  
101//!   Default: `false`.
102//!   Alias: `constant`.
103//!   - `func`/`func = <bool>`: Whether to generate static methods that return default values.
104//!   The corresponding constant name is the snake_case version of the current enumeration and has a `default_` prefix.  
105//!   Default: `true`.
106//!   Alias: `fn`, `function`.
107//! 
108//! **Note:** This attribute can be added to an enum body or to a single variant.
109//! If added to the enum body, it will override the default generated configuration.
110//! 
111//! **Basic Usage:**
112//! 
113//! ```rust
114//! use fancy_default::VariantDefault;
115//! 
116//! #[derive(Debug, VariantDefault, PartialEq, Eq)]
117//! #[variant(const)]
118//! enum Enum {
119//!     Plain,
120//!     #[variant(const = false)]
121//!     Struct {
122//!         #[default(expr = "123".to_owned())]
123//!         name: String,
124//!     },
125//!     Tuple(#[default = 10] usize),
126//! }
127//! 
128//! 
129//! assert_eq!(Enum::PLAIN, Enum::Plain);
130//! assert_eq!(
131//!     Enum::default_struct(),
132//!     Enum::Struct {
133//!         name: "123".to_owned()
134//!     }
135//! );
136//! ```
137//! 
138//! ## MSRV
139//! 
140//! The theoretical minimum rust version of this derived macro is 1.34,
141//! which allows passing `TokenStream` to `MetaList` from that version onwards.
142//! 
143//! ## License
144//! 
145//! This library is licensed under the MIT license or the Apache v2.0 license.
146
147
148#![no_std]
149
150/// Derive macros provided by the library.
151pub mod derive;
152/// `Default`-like traits implemented by the derive macros.
153pub mod traits;
154
155pub use derive::{ConstDefault, Default, VariantDefault};
156pub use traits::ConstDefault;
fancy_default/lib.rs

fancy_default/
lib.rs
