ctl-core 0.7.0

A framework for clap programs: typed results, help, and terminal or JSON output
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

use clap::Args;

use crate::color::ColorMode;
use crate::flags::resolve_color;
use crate::format::OutputFormat;

/// Output flags for the root parser: format, colour, and quiet. Flatten it with
/// `#[command(flatten)]`.
///
/// The flags are global, so a subcommand accepts them too. [`Self::view`]
/// builds the [`View`] for the parsed flags. A CLI that already uses `-c`
/// flattens [`ColorLong`](super::ColorLong) plus [`FormatArgs`] instead.
#[cfg_attr(
    feature = "view",
    doc = "",
    doc = "[`Self::view`]: Self::view",
    doc = "[`View`]: crate::view::View"
)]
#[cfg_attr(
    not(feature = "view"),
    doc = "",
    doc = "[`Self::view`]: crate#cargo-features",
    doc = "[`View`]: crate#cargo-features"
)]
///
/// The colour flags are private, so [`Self::color`] is their only reader and
/// `--no-color` is never skipped. A flag can join the struct in a minor
/// release.
#[derive(Args, Clone, Debug, Default, Eq, PartialEq)]
#[command(about = None, long_about = None)]
#[non_exhaustive]
pub struct OutputArgs {
    /// Output representation.
    #[arg(
        short = 'f',
        long,
        global = true,
        value_enum,
        default_value = "pretty",
        help_heading = "Output"
    )]
    pub format: OutputFormat,
    /// Pretty-output colour policy. JSON never contains ANSI.
    #[arg(
        short = 'c',
        long,
        global = true,
        value_enum,
        default_value = "auto",
        help_heading = "Output"
    )]
    color: ColorMode,
    /// Force colourless pretty output. Wins over `--color`.
    #[arg(long, global = true, help_heading = "Output")]
    no_color: bool,
    /// Suppress successful pretty output.
    #[arg(short = 'q', long, global = true, help_heading = "Output")]
    pub quiet: bool,
}

impl OutputArgs {
    /// The colour mode in force: [`ColorMode::Never`] when `--no-color` is
    /// set, otherwise the `--color` value.
    #[must_use]
    pub fn color(&self) -> ColorMode {
        resolve_color(self.color, self.no_color)
    }

    /// Build the [`View`](crate::view::View) for these flags: the format, the
    /// quiet setting, and the colour mode in force.
    #[cfg(feature = "view")]
    #[must_use]
    pub fn view(&self) -> crate::view::View {
        crate::view::View::new(self.format, self.color()).quiet(self.quiet)
    }
}

/// `-f/--format` and `-q/--quiet`, with no colour flags.
///
/// Pair it with [`ColorLong`](super::ColorLong) when the CLI owns `-c`, and
/// pass the colour mode to [`Self::view`].
#[cfg_attr(feature = "view", doc = "", doc = "[`Self::view`]: Self::view")]
#[cfg_attr(
    not(feature = "view"),
    doc = "",
    doc = "[`Self::view`]: crate#cargo-features"
)]
///
/// A flag can join it in a minor release.
#[derive(Args, Clone, Debug, Default, Eq, PartialEq)]
#[command(about = None, long_about = None)]
#[non_exhaustive]
pub struct FormatArgs {
    /// Output representation.
    #[arg(
        short = 'f',
        long,
        global = true,
        value_enum,
        default_value = "pretty",
        help_heading = "Output"
    )]
    pub format: OutputFormat,
    /// Suppress successful pretty output.
    #[arg(short = 'q', long, global = true, help_heading = "Output")]
    pub quiet: bool,
}

impl FormatArgs {
    /// Build the [`View`](crate::view::View) for these flags, with `color` as
    /// the colour mode and the parsed format and quiet setting.
    #[cfg(feature = "view")]
    #[must_use]
    pub fn view(&self, color: ColorMode) -> crate::view::View {
        crate::view::View::new(self.format, color).quiet(self.quiet)
    }
}

/// `--format` and `-q`/`--quiet` without the `-f` short flag, for CLIs that
/// already use `-f` for a domain flag such as `--file`.
///
/// A flag can join it in a minor release.
#[derive(Args, Clone, Debug, Default, Eq, PartialEq)]
#[command(about = None, long_about = None)]
#[non_exhaustive]
pub struct FormatLong {
    /// Output representation.
    #[arg(
        long,
        global = true,
        value_enum,
        default_value = "pretty",
        help_heading = "Output"
    )]
    pub format: OutputFormat,
    /// Suppress successful pretty output.
    #[arg(short = 'q', long, global = true, help_heading = "Output")]
    pub quiet: bool,
}

impl FormatLong {
    /// Build the [`View`](crate::view::View) for these flags, with `color` as
    /// the colour mode and the parsed format and quiet setting.
    #[cfg(feature = "view")]
    #[must_use]
    pub fn view(&self, color: ColorMode) -> crate::view::View {
        crate::view::View::new(self.format, color).quiet(self.quiet)
    }
}