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 //!
21 //!   ```rust
22 //!   use std::string::ToString;
23 //!   use strum;
24 //!   use strum_macros;
25 //!
26 //!   #[derive(Debug, Eq, PartialEq, strum_macros::ToString)]
27 //!   #[strum(serialize_all = "snake_case")]
28 //!   enum Brightness {
29 //!       DarkBlack,
30 //!       Dim {
31 //!           glow: usize,
32 //!       },
33 //!       #[strum(serialize = "bright")]
34 //!       BrightWhite,
35 //!   }
36 //!
37 //!   assert_eq!(
38 //!       String::from("dark_black"),
39 //!       Brightness::DarkBlack.to_string().as_ref()
40 //!   );
41 //!   assert_eq!(
42 //!       String::from("dim"),
43 //!       Brightness::Dim { glow: 0 }.to_string().as_ref()
44 //!   );
45 //!   assert_eq!(
46 //!       String::from("bright"),
47 //!       Brightness::BrightWhite.to_string().as_ref()
48 //!   );
49 //!   ```
50 //!
51 //! - You can also apply the `#[strum(ascii_case_insensitive)]` attribute to the enum,
52 //!   and this has the same effect of applying it to every variant.
53 //!
54 //! ## Attributes on Variants
55 //!
56 //! Custom attributes are applied to a variant by adding `#[strum(parameter="value")]` to the variant.
57 //!
58 //! - `serialize="..."`: Changes the text that `FromStr()` looks for when parsing a string. This attribute can
59 //!    be applied multiple times to an element and the enum variant will be parsed if any of them match.
60 //!
61 //! - `to_string="..."`: Similar to `serialize`. This value will be included when using `FromStr()`. More importantly,
62 //!    this specifies what text to use when calling `variant.to_string()` with the `Display` derivation, or when calling `variant.as_ref()` with `AsRefStr`.
63 //!
64 //! - `default`: Applied to a single variant of an enum. The variant must be a Tuple-like
65 //!    variant with a single piece of data that can be create from a `&str` i.e. `T: From<&str>`.
66 //!    The generated code will now return the variant with the input string captured as shown below
67 //!    instead of failing.
68 //!
69 //!     ```rust,ignore
70 //!     // Replaces this:
71 //!     _ => Err(strum::ParseError::VariantNotFound)
72 //!     // With this in generated code:
73 //!     default => Ok(Variant(default.into()))
74 //!     ```
75 //!     The plugin will fail if the data doesn't implement From<&str>. You can only have one `default`
76 //!     on your enum.
77 //!
78 //! - `disabled`: removes variant from generated code.
79 //!
80 //! - `ascii_case_insensitive`: makes the comparison to this variant case insensitive (ASCII only).
81 //!   If the whole enum is marked `ascii_case_insensitive`, you can specify `ascii_case_insensitive = false`
82 //!   to disable case insensitivity on this v ariant.
83 //!
84 //! - `message=".."`: Adds a message to enum variant. This is used in conjunction with the `EnumMessage`
85 //!    trait to associate a message with a variant. If `detailed_message` is not provided,
86 //!    then `message` will also be returned when get_detailed_message() is called.
87 //!
88 //! - `detailed_message=".."`: Adds a more detailed message to a variant. If this value is omitted, then
89 //!    `message` will be used in it's place.
90 //!
91 //! - `props(key="value")`: Enables associating additional information with a given variant.
92