Skip to main content

cornerstone/
spec.rs

1//! The declarative model an author fills in: commands, positional arguments,
2//! and flags. This is pure data — the parser ([`crate::parse`]) consumes it and
3//! the help renderer ([`crate::help`]) prints it. Authors never touch these
4//! structs directly; they build them through the fluent methods on
5//! [`crate::app::App`] and [`Command`].
6
7/// A positional argument to a command, e.g. the `<name>` in `uff create <name>`.
8#[derive(Debug, Clone)]
9pub struct Arg {
10    pub name: String,
11    pub help: String,
12    pub required: bool,
13    /// If true, this argument soaks up all remaining positionals (variadic).
14    pub variadic: bool,
15}
16
17impl Arg {
18    pub fn new<S: Into<String>>(name: S) -> Self {
19        Arg {
20            name: name.into(),
21            help: String::new(),
22            required: true,
23            variadic: false,
24        }
25    }
26    pub fn help<S: Into<String>>(mut self, h: S) -> Self {
27        self.help = h.into();
28        self
29    }
30    pub fn optional(mut self) -> Self {
31        self.required = false;
32        self
33    }
34    pub fn variadic(mut self) -> Self {
35        self.variadic = true;
36        self
37    }
38}
39
40/// What kind of value a flag takes.
41#[derive(Debug, Clone, PartialEq, Eq)]
42pub enum FlagKind {
43    /// A boolean switch: present or absent (`--verbose`).
44    Bool,
45    /// Takes a single value (`--output file`, `-o file`).
46    Value,
47}
48
49/// A flag / option, e.g. `-o, --output <FILE>`.
50#[derive(Debug, Clone)]
51pub struct Flag {
52    pub long: String,
53    pub short: Option<char>,
54    pub value_name: Option<String>,
55    pub help: String,
56    pub kind: FlagKind,
57    /// Default value for a value-flag when the user omits it.
58    pub default: Option<String>,
59}
60
61impl Flag {
62    /// A boolean switch flag.
63    pub fn switch<S: Into<String>>(long: S) -> Self {
64        Flag {
65            long: long.into(),
66            short: None,
67            value_name: None,
68            help: String::new(),
69            kind: FlagKind::Bool,
70            default: None,
71        }
72    }
73    /// A value-taking option.
74    pub fn value<S: Into<String>>(long: S) -> Self {
75        let long = long.into();
76        let vn = long.to_uppercase();
77        Flag {
78            long,
79            short: None,
80            value_name: Some(vn),
81            help: String::new(),
82            kind: FlagKind::Value,
83            default: None,
84        }
85    }
86    pub fn short(mut self, c: char) -> Self {
87        self.short = Some(c);
88        self
89    }
90    pub fn help<S: Into<String>>(mut self, h: S) -> Self {
91        self.help = h.into();
92        self
93    }
94    pub fn value_name<S: Into<String>>(mut self, n: S) -> Self {
95        self.value_name = Some(n.into());
96        self
97    }
98    pub fn default<S: Into<String>>(mut self, d: S) -> Self {
99        self.default = Some(d.into());
100        self
101    }
102
103    /// Render the invocation token for help, e.g. `-o, --output <FILE>`.
104    pub(crate) fn invocation(&self) -> String {
105        let mut s = String::new();
106        if let Some(c) = self.short {
107            s.push('-');
108            s.push(c);
109            s.push_str(", ");
110        } else {
111            s.push_str("    ");
112        }
113        s.push_str("--");
114        s.push_str(&self.long);
115        if self.kind == FlagKind::Value {
116            let vn = self.value_name.as_deref().unwrap_or("VALUE");
117            s.push_str(&format!(" <{}>", vn));
118        }
119        s
120    }
121}
122
123/// A subcommand. The `run` closure is stored on the app side; this struct holds
124/// only the descriptive spec used for parsing and help.
125#[derive(Clone)]
126pub struct Command {
127    pub name: String,
128    pub about: String,
129    /// A longer description shown in the command's own `--help`.
130    pub long_about: String,
131    pub args: Vec<Arg>,
132    pub flags: Vec<Flag>,
133    /// Example invocations shown in long help.
134    pub examples: Vec<String>,
135    /// Marks the command as performing destructive on-disk changes, so the app
136    /// can enforce the confirmation/`--sudo` guards.
137    pub destructive: bool,
138    /// Child command specs, when this command is a group. Populated by the app's
139    /// group builder so help and completion can render the nested tree. Empty
140    /// for leaf commands.
141    pub subcommands: Vec<Command>,
142}
143
144impl Command {
145    pub fn new<S: Into<String>>(name: S) -> Self {
146        Command {
147            name: name.into(),
148            about: String::new(),
149            long_about: String::new(),
150            args: Vec::new(),
151            flags: Vec::new(),
152            examples: Vec::new(),
153            destructive: false,
154            subcommands: Vec::new(),
155        }
156    }
157    /// Whether this command is a group (has child subcommands).
158    pub fn is_group(&self) -> bool {
159        !self.subcommands.is_empty()
160    }
161}