1use crate::builder::PossibleValue;
2use crate::derive::ValueEnum;
3
4/// Represents the color preferences for program output
5#[derive(Debug, Copy, Clone, Eq, PartialEq)]
6pub enum ColorChoice {
7 /// Enables colored output only when the output is going to a terminal or TTY.
8 ///
9 /// <div class="warning">
10 ///
11 /// **NOTE:** This is the default behavior of `clap`.
12 ///
13 /// </div>
14 ///
15 /// # Examples
16 ///
17 /// ```rust
18 /// # #[cfg(feature = "color")] {
19 /// # use clap_builder as clap;
20 /// # use clap::{Command, ColorChoice};
21 /// Command::new("myprog")
22 /// .color(ColorChoice::Auto)
23 /// .get_matches();
24 /// # }
25 /// ```
26 Auto,
27
28 /// Enables colored output regardless of whether or not the output is going to a terminal/TTY.
29 ///
30 /// # Examples
31 ///
32 /// ```rust
33 /// # #[cfg(feature = "color")] {
34 /// # use clap_builder as clap;
35 /// # use clap::{Command, ColorChoice};
36 /// Command::new("myprog")
37 /// .color(ColorChoice::Always)
38 /// .get_matches();
39 /// # }
40 /// ```
41 Always,
42
43 /// Disables colored output no matter if the output is going to a terminal/TTY, or not.
44 ///
45 /// # Examples
46 ///
47 /// ```rust
48 /// # #[cfg(feature = "color")] {
49 /// # use clap_builder as clap;
50 /// # use clap::{Command, ColorChoice};
51 /// Command::new("myprog")
52 /// .color(ColorChoice::Never)
53 /// .get_matches();
54 /// # }
55 /// ```
56 Never,
57}
58
59impl ColorChoice {
60 /// Report all `possible_values`
61 pub fn possible_values() -> impl Iterator<Item = PossibleValue> {
62 Self::value_variants()
63 .iter()
64 .filter_map(ValueEnum::to_possible_value)
65 }
66}
67
68impl Default for ColorChoice {
69 fn default() -> Self {
70 Self::Auto
71 }
72}
73
74impl std::fmt::Display for ColorChoice {
75 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
76 self.to_possible_value()
77 .expect(msg:"no values are skipped")
78 .get_name()
79 .fmt(f)
80 }
81}
82
83impl std::str::FromStr for ColorChoice {
84 type Err = String;
85
86 fn from_str(s: &str) -> Result<Self, Self::Err> {
87 for variant: &ColorChoice in Self::value_variants() {
88 if variant.to_possible_value().unwrap().matches(value:s, ignore_case:false) {
89 return Ok(*variant);
90 }
91 }
92 Err(format!("invalid variant: {s}"))
93 }
94}
95
96impl ValueEnum for ColorChoice {
97 fn value_variants<'a>() -> &'a [Self] {
98 &[Self::Auto, Self::Always, Self::Never]
99 }
100
101 fn to_possible_value(&self) -> Option<PossibleValue> {
102 Some(match self {
103 Self::Auto => PossibleValue::new(name:"auto"),
104 Self::Always => PossibleValue::new(name:"always"),
105 Self::Never => PossibleValue::new(name:"never"),
106 })
107 }
108}
109