fancy_default/lib.rs
1//! # `fancy-default`
2//!
3//! This library provides enhancements to the standard library's `Default` derive macro.
4//!
5//! 
6//! 
7//! 
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;