1  //! # Documentation for Additional Attributes
2  //!
3  //! ## Attributes on Enums
4  //!
5  //! Strum supports several custom attributes to modify the generated code. At the enum level, the following attributes are supported:
6  //!
7  //! - `#[strum(serialize_all = "case_style")]` attribute can be used to change the case used when serializing to and deserializing
8  //!   from strings. This feature is enabled by [withoutboats/heck](https://github.com/withoutboats/heck) and supported case styles are:
9  //!
10  //!   - `camelCase`
11  //!   - `PascalCase`
12  //!   - `kebab-case`
13  //!   - `snake_case`
14  //!   - `SCREAMING_SNAKE_CASE`
15  //!   - `SCREAMING-KEBAB-CASE`
16  //!   - `lowercase`
17  //!   - `UPPERCASE`
18  //!   - `title_case`
19  //!   - `mixed_case`
20  //!   - `Train-Case`
21  //!
22  //!   ```rust
23  //!   use strum_macros;
24  //!
25  //!   #[derive(Debug, Eq, PartialEq, strum_macros::Display)]
26  //!   #[strum(serialize_all = "snake_case")]
27  //!   enum Brightness {
28  //!       DarkBlack,
29  //!       Dim {
30  //!           glow: usize,
31  //!       },
32  //!       #[strum(serialize = "bright")]
33  //!       BrightWhite,
34  //!   }
35  //!
36  //!   assert_eq!(
37  //!       String::from("dark_black"),
38  //!       Brightness::DarkBlack.to_string().as_ref()
39  //!   );
40  //!   assert_eq!(
41  //!       String::from("dim"),
42  //!       Brightness::Dim { glow: 0 }.to_string().as_ref()
43  //!   );
44  //!   assert_eq!(
45  //!       String::from("bright"),
46  //!       Brightness::BrightWhite.to_string().as_ref()
47  //!   );
48  //!   ```
49  //!
50  //! - You can also apply the `#[strum(ascii_case_insensitive)]` attribute to the enum,
51  //!   and this has the same effect of applying it to every variant.
52  //!
53  //! ## Attributes on Variants
54  //!
55  //! Custom attributes are applied to a variant by adding `#[strum(parameter="value")]` to the variant.
56  //!
57  //! - `serialize="..."`: Changes the text that `FromStr()` looks for when parsing a string. This attribute can
58  //!    be applied multiple times to an element and the enum variant will be parsed if any of them match.
59  //!
60  //! - `to_string="..."`: Similar to `serialize`. This value will be included when using `FromStr()`. More importantly,
61  //!    this specifies what text to use when calling `variant.to_string()` with the `Display` derivation, or when calling `variant.as_ref()` with `AsRefStr`.
62  //!
63  //! - `default`: Applied to a single variant of an enum. The variant must be a Tuple-like
64  //!    variant with a single piece of data that can be create from a `&str` i.e. `T: From<&str>`.
65  //!    The generated code will now return the variant with the input string captured as shown below
66  //!    instead of failing.
67  //!
68  //!     ```text
69  //!     // Replaces this:
70  //!     _ => Err(strum::ParseError::VariantNotFound)
71  //!     // With this in generated code:
72  //!     default => Ok(Variant(default.into()))
73  //!     ```
74  //!     The plugin will fail if the data doesn't implement From<&str>. You can only have one `default`
75  //!     on your enum.
76  //!
77  //! - `disabled`: removes variant from generated code.
78  //!
79  //! - `ascii_case_insensitive`: makes the comparison to this variant case insensitive (ASCII only).
80  //!   If the whole enum is marked `ascii_case_insensitive`, you can specify `ascii_case_insensitive = false`
81  //!   to disable case insensitivity on this v ariant.
82  //!
83  //! - `message=".."`: Adds a message to enum variant. This is used in conjunction with the `EnumMessage`
84  //!    trait to associate a message with a variant. If `detailed_message` is not provided,
85  //!    then `message` will also be returned when `get_detailed_message` is called.
86  //!
87  //! - `detailed_message=".."`: Adds a more detailed message to a variant. If this value is omitted, then
88  //!    `message` will be used in it's place.
89  //!
90  //! - Structured documentation, as in `/// ...`: If using `EnumMessage`, is accessible via get_documentation().
91  //!
92  //! - `props(key="value")`: Enables associating additional information with a given variant.
93