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//! ```text
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//! - Structured documentation, as in `/// ...`: If using `EnumMessage`, is accessible via get_documentation().
92//!
93//! - `props(key="value")`: Enables associating additional information with a given variant.
94