crokey/
format.rs

1//! Crokey helps incorporate configurable keybindings in [crossterm](https://github.com/crossterm-rs/crossterm)
2//! based terminal applications by providing functions
3//! - parsing key combinations from strings
4//! - describing key combinations in strings
5
6use {
7    crate::KeyCombination,
8    crossterm::event::{KeyCode::*, KeyModifiers},
9    std::fmt,
10};
11
12/// A formatter to produce key combinations descriptions.
13///
14/// ```
15/// use {
16///     crokey::*,
17///     crossterm::event::{
18///         KeyCode,
19///         KeyEvent,
20///         KeyModifiers,
21///     },
22/// };
23///
24/// let format = KeyCombinationFormat::default();
25/// assert_eq!(format.to_string(key!(shift-a)), "Shift-a");
26/// assert_eq!(format.to_string(key!(ctrl-c)), "Ctrl-c");
27///
28/// // A more compact format
29/// let format = KeyCombinationFormat::default()
30///     .with_implicit_shift()
31///     .with_control("^");
32/// assert_eq!(format.to_string(key!(shift-a)), "A");
33/// assert_eq!(format.to_string(key!(ctrl-c)), "^c");
34///
35/// // A long format with lowercased modifiers
36/// let format = KeyCombinationFormat::default()
37///     .with_lowercase_modifiers();
38/// assert_eq!(format.to_string(key!(ctrl-enter)), "ctrl-Enter");
39/// assert_eq!(format.to_string(key!(home)), "Home");
40/// assert_eq!(
41///     format.to_string(
42///         KeyCombination::new(
43///             KeyCode::F(6),
44///             KeyModifiers::ALT,
45///         )
46///     ),
47///     "alt-F6",
48/// );
49/// assert_eq!(
50///     format.to_string(
51///         KeyCombination::new(
52///             (KeyCode::Char('u'), KeyCode::Char('i')),
53///             KeyModifiers::NONE,
54///         )
55///     ),
56///     "i-u",
57/// );
58///
59/// ```
60#[derive(Debug, Clone)]
61pub struct KeyCombinationFormat {
62    pub control: String,
63    pub alt: String,
64    pub shift: String,
65    pub enter: String,
66    pub uppercase_shift: bool,
67    pub key_separator: String,
68}
69
70impl Default for KeyCombinationFormat {
71    fn default() -> Self {
72        Self {
73            control: "Ctrl-".to_string(),
74            alt: "Alt-".to_string(),
75            shift: "Shift-".to_string(),
76            enter: "Enter".to_string(),
77            uppercase_shift: false,
78            key_separator: "-".to_string(),
79        }
80    }
81}
82
83impl KeyCombinationFormat {
84    pub fn with_lowercase_modifiers(mut self) -> Self {
85        self.control = self.control.to_lowercase();
86        self.alt = self.alt.to_lowercase();
87        self.shift = self.shift.to_lowercase();
88        self
89    }
90    pub fn with_control<S: Into<String>>(mut self, s: S) -> Self {
91        self.control = s.into();
92        self
93    }
94    pub fn with_alt<S: Into<String>>(mut self, s: S) -> Self {
95        self.alt = s.into();
96        self
97    }
98    pub fn with_shift<S: Into<String>>(mut self, s: S) -> Self {
99        self.shift = s.into();
100        self
101    }
102    pub fn with_implicit_shift(mut self) -> Self {
103        self.shift = "".to_string();
104        self.uppercase_shift = true;
105        self
106    }
107    /// return a wrapper of the key implementing Display
108    ///
109    /// ```
110    /// use crokey::*;
111    /// let format = KeyCombinationFormat::default();
112    /// let k = format.format(key!(f6));
113    /// let s = format!("k={}", k);
114    /// assert_eq!(s, "k=F6");
115    /// ```
116    pub fn format<K: Into<KeyCombination>>(&self, key: K) -> FormattedKeyCombination {
117        FormattedKeyCombination { format: self, key: key.into() }
118    }
119    /// return the key formatted into a string
120    ///
121    /// `format.to_string(key)` is equivalent to `format.format(key).to_string()`.
122    pub fn to_string<K: Into<KeyCombination>>(&self, key: K) -> String {
123        self.format(key).to_string()
124    }
125}
126
127pub struct FormattedKeyCombination<'s> {
128    format: &'s KeyCombinationFormat,
129    key: KeyCombination,
130}
131
132impl fmt::Display for FormattedKeyCombination<'_> {
133    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
134        let format = &self.format;
135        let key = &self.key;
136        if key.modifiers.contains(KeyModifiers::CONTROL) {
137            write!(f, "{}", format.control)?;
138        }
139        if key.modifiers.contains(KeyModifiers::ALT) {
140            write!(f, "{}", format.alt)?;
141        }
142        if key.modifiers.contains(KeyModifiers::SHIFT) {
143            write!(f, "{}", format.shift)?;
144        }
145        for (i, code) in key.codes.iter().enumerate() {
146            if i > 0 {
147                write!(f, "{}", format.key_separator)?;
148            }
149            match code {
150                Char(' ') => {
151                    write!(f, "Space")?;
152                }
153                Char('-') => {
154                    write!(f, "Hyphen")?;
155                }
156                Char('\r') | Char('\n') | Enter => {
157                    write!(f, "{}", format.enter)?;
158                }
159                Char(c) if key.modifiers.contains(KeyModifiers::SHIFT) && format.uppercase_shift => {
160                    write!(f, "{}", c.to_ascii_uppercase())?;
161                }
162                Char(c) => {
163                    write!(f, "{}", c.to_ascii_lowercase())?;
164                }
165                F(u) => {
166                    write!(f, "F{u}")?;
167                }
168                _ => {
169                    write!(f, "{:?}", code)?;
170                }
171            }
172        }
173        Ok(())
174    }
175}
crokey/format.rs

crokey/
format.rs
