termion/
input.rs

Help
1//! User input.
2
3use std::io::{self, Read, Write};
4use std::ops;
5
6use event::{self, Event, Key};
7use raw::IntoRawMode;
8
9/// An iterator over input keys.
10pub struct Keys<R> {
11    iter: Events<R>,
12}
13
14impl<R: Read> Iterator for Keys<R> {
15    type Item = Result<Key, io::Error>;
16
17    fn next(&mut self) -> Option<Result<Key, io::Error>> {
18        loop {
19            match self.iter.next() {
20                Some(Ok(Event::Key(k))) => return Some(Ok(k)),
21                Some(Ok(_)) => continue,
22                e @ Some(Err(_)) => e,
23                None => return None,
24            };
25        }
26    }
27}
28
29/// An iterator over input events.
30pub struct Events<R>  {
31    inner: EventsAndRaw<R>
32}
33
34impl<R: Read> Iterator for Events<R> {
35    type Item = Result<Event, io::Error>;
36
37    fn next(&mut self) -> Option<Result<Event, io::Error>> {
38        self.inner.next().map(|tuple| tuple.map(|(event, _raw)| event))
39    }
40}
41
42/// An iterator over input events and the bytes that define them.
43pub struct EventsAndRaw<R> {
44    source: R,
45    leftover: Option<u8>,
46}
47
48impl<R: Read> Iterator for EventsAndRaw<R> {
49    type Item = Result<(Event, Vec<u8>), io::Error>;
50
51    fn next(&mut self) -> Option<Result<(Event, Vec<u8>), io::Error>> {
52        let source = &mut self.source;
53
54        if let Some(c) = self.leftover {
55            // we have a leftover byte, use it
56            self.leftover = None;
57            return Some(parse_event(c, &mut source.bytes()));
58        }
59
60        // Here we read two bytes at a time. We need to distinguish between single ESC key presses,
61        // and escape sequences (which start with ESC or a x1B byte). The idea is that if this is
62        // an escape sequence, we will read multiple bytes (the first byte being ESC) but if this
63        // is a single ESC keypress, we will only read a single byte.
64        let mut buf = [0u8; 2];
65        let res = match source.read(&mut buf) {
66            Ok(0) => return None,
67            Ok(1) => {
68                match buf[0] {
69                    b'\x1B' => Ok((Event::Key(Key::Esc), vec![b'\x1B'])),
70                    c => parse_event(c, &mut source.bytes()),
71                }
72            }
73            Ok(2) => {
74                let mut option_iter = &mut Some(buf[1]).into_iter();
75                let result = {
76                    let mut iter = option_iter.map(|c| Ok(c)).chain(source.bytes());
77                    parse_event(buf[0], &mut iter)
78                };
79                // If the option_iter wasn't consumed, keep the byte for later.
80                self.leftover = option_iter.next();
81                result
82            }
83            Ok(_) => unreachable!(),
84            Err(e) => Err(e),
85        };
86
87        Some(res)
88    }
89}
90
91fn parse_event<I>(item: u8, iter: &mut I) -> Result<(Event, Vec<u8>), io::Error>
92    where I: Iterator<Item = Result<u8, io::Error>>
93{
94    let mut buf = vec![item];
95    let result = {
96        let mut iter = iter.inspect(|byte| if let &Ok(byte) = byte {
97                                        buf.push(byte);
98                                    });
99        event::parse_event(item, &mut iter)
100    };
101    result.or(Ok(Event::Unsupported(buf.clone()))).map(|e| (e, buf))
102}
103
104
105/// Extension to `Read` trait.
106pub trait TermRead {
107    /// An iterator over input events.
108    fn events(self) -> Events<Self> where Self: Sized;
109
110    /// An iterator over key inputs.
111    fn keys(self) -> Keys<Self> where Self: Sized;
112
113    /// Read a line.
114    ///
115    /// EOT and ETX will abort the prompt, returning `None`. Newline or carriage return will
116    /// complete the input.
117    fn read_line(&mut self) -> io::Result<Option<String>>;
118
119    /// Read a password.
120    ///
121    /// EOT and ETX will abort the prompt, returning `None`. Newline or carriage return will
122    /// complete the input.
123    fn read_passwd<W: Write>(&mut self, writer: &mut W) -> io::Result<Option<String>> {
124        let _raw = try!(writer.into_raw_mode());
125        self.read_line()
126    }
127}
128
129
130impl<R: Read + TermReadEventsAndRaw> TermRead for R {
131    fn events(self) -> Events<Self> {
132        Events {
133            inner: self.events_and_raw()
134        }
135    }
136    fn keys(self) -> Keys<Self> {
137        Keys { iter: self.events() }
138    }
139
140    fn read_line(&mut self) -> io::Result<Option<String>> {
141        let mut buf = Vec::with_capacity(30);
142
143        for c in self.bytes() {
144            match c {
145                Err(e) => return Err(e),
146                Ok(0) | Ok(3) | Ok(4) => return Ok(None),
147                Ok(0x7f) => {
148                    buf.pop();
149                }
150                Ok(b'\n') | Ok(b'\r') => break,
151                Ok(c) => buf.push(c),
152            }
153        }
154
155        let string = try!(String::from_utf8(buf)
156            .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e)));
157        Ok(Some(string))
158    }
159}
160
161/// Extension to `TermRead` trait. A separate trait in order to maintain backwards compatibility.
162pub trait TermReadEventsAndRaw {
163    /// An iterator over input events and the bytes that define them.
164    fn events_and_raw(self) -> EventsAndRaw<Self> where Self: Sized;
165}
166
167impl<R: Read> TermReadEventsAndRaw for R {
168    fn events_and_raw(self) -> EventsAndRaw<Self> {
169        EventsAndRaw {
170            source: self,
171            leftover: None,
172        }
173    }
174}
175
176/// A sequence of escape codes to enable terminal mouse support.
177const ENTER_MOUSE_SEQUENCE: &'static str = csi!("?1000h\x1b[?1002h\x1b[?1015h\x1b[?1006h");
178
179/// A sequence of escape codes to disable terminal mouse support.
180const EXIT_MOUSE_SEQUENCE: &'static str = csi!("?1006l\x1b[?1015l\x1b[?1002l\x1b[?1000l");
181
182/// A terminal with added mouse support.
183///
184/// This can be obtained through the `From` implementations.
185pub struct MouseTerminal<W: Write> {
186    term: W,
187}
188
189impl<W: Write> From<W> for MouseTerminal<W> {
190    fn from(mut from: W) -> MouseTerminal<W> {
191        from.write_all(ENTER_MOUSE_SEQUENCE.as_bytes()).unwrap();
192
193        MouseTerminal { term: from }
194    }
195}
196
197impl<W: Write> Drop for MouseTerminal<W> {
198    fn drop(&mut self) {
199        self.term.write_all(EXIT_MOUSE_SEQUENCE.as_bytes()).unwrap();
200    }
201}
202
203impl<W: Write> ops::Deref for MouseTerminal<W> {
204    type Target = W;
205
206    fn deref(&self) -> &W {
207        &self.term
208    }
209}
210
211impl<W: Write> ops::DerefMut for MouseTerminal<W> {
212    fn deref_mut(&mut self) -> &mut W {
213        &mut self.term
214    }
215}
216
217impl<W: Write> Write for MouseTerminal<W> {
218    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
219        self.term.write(buf)
220    }
221
222    fn flush(&mut self) -> io::Result<()> {
223        self.term.flush()
224    }
225}
226
227#[cfg(test)]
228mod test {
229    use super::*;
230    use std::io;
231    use event::{Key, Event, MouseEvent, MouseButton};
232
233    #[test]
234    fn test_keys() {
235        let mut i = b"\x1Bayo\x7F\x1B[D".keys();
236
237        assert_eq!(i.next().unwrap().unwrap(), Key::Alt('a'));
238        assert_eq!(i.next().unwrap().unwrap(), Key::Char('y'));
239        assert_eq!(i.next().unwrap().unwrap(), Key::Char('o'));
240        assert_eq!(i.next().unwrap().unwrap(), Key::Backspace);
241        assert_eq!(i.next().unwrap().unwrap(), Key::Left);
242        assert!(i.next().is_none());
243    }
244
245    #[test]
246    fn test_events() {
247        let mut i =
248            b"\x1B[\x00bc\x7F\x1B[D\
249                    \x1B[M\x00\x22\x24\x1B[<0;2;4;M\x1B[32;2;4M\x1B[<0;2;4;m\x1B[35;2;4Mb"
250                    .events();
251
252        assert_eq!(i.next().unwrap().unwrap(),
253                   Event::Unsupported(vec![0x1B, b'[', 0x00]));
254        assert_eq!(i.next().unwrap().unwrap(), Event::Key(Key::Char('b')));
255        assert_eq!(i.next().unwrap().unwrap(), Event::Key(Key::Char('c')));
256        assert_eq!(i.next().unwrap().unwrap(), Event::Key(Key::Backspace));
257        assert_eq!(i.next().unwrap().unwrap(), Event::Key(Key::Left));
258        assert_eq!(i.next().unwrap().unwrap(),
259                   Event::Mouse(MouseEvent::Press(MouseButton::WheelUp, 2, 4)));
260        assert_eq!(i.next().unwrap().unwrap(),
261                   Event::Mouse(MouseEvent::Press(MouseButton::Left, 2, 4)));
262        assert_eq!(i.next().unwrap().unwrap(),
263                   Event::Mouse(MouseEvent::Press(MouseButton::Left, 2, 4)));
264        assert_eq!(i.next().unwrap().unwrap(),
265                   Event::Mouse(MouseEvent::Release(2, 4)));
266        assert_eq!(i.next().unwrap().unwrap(),
267                   Event::Mouse(MouseEvent::Release(2, 4)));
268        assert_eq!(i.next().unwrap().unwrap(), Event::Key(Key::Char('b')));
269        assert!(i.next().is_none());
270    }
271
272    #[test]
273    fn test_events_and_raw() {
274        let input = b"\x1B[\x00bc\x7F\x1B[D\
275                    \x1B[M\x00\x22\x24\x1B[<0;2;4;M\x1B[32;2;4M\x1B[<0;2;4;m\x1B[35;2;4Mb";
276        let mut output = Vec::<u8>::new();
277        {
278            let mut i = input.events_and_raw().map(|res| res.unwrap())
279                .inspect(|&(_, ref raw)| { output.extend(raw); }).map(|(event, _)| event);
280
281            assert_eq!(i.next().unwrap(),
282            Event::Unsupported(vec![0x1B, b'[', 0x00]));
283            assert_eq!(i.next().unwrap(), Event::Key(Key::Char('b')));
284            assert_eq!(i.next().unwrap(), Event::Key(Key::Char('c')));
285            assert_eq!(i.next().unwrap(), Event::Key(Key::Backspace));
286            assert_eq!(i.next().unwrap(), Event::Key(Key::Left));
287            assert_eq!(i.next().unwrap(),
288            Event::Mouse(MouseEvent::Press(MouseButton::WheelUp, 2, 4)));
289            assert_eq!(i.next().unwrap(),
290            Event::Mouse(MouseEvent::Press(MouseButton::Left, 2, 4)));
291            assert_eq!(i.next().unwrap(),
292            Event::Mouse(MouseEvent::Press(MouseButton::Left, 2, 4)));
293            assert_eq!(i.next().unwrap(),
294            Event::Mouse(MouseEvent::Release(2, 4)));
295            assert_eq!(i.next().unwrap(),
296            Event::Mouse(MouseEvent::Release(2, 4)));
297            assert_eq!(i.next().unwrap(), Event::Key(Key::Char('b')));
298            assert!(i.next().is_none());
299        }
300
301        assert_eq!(input.iter().map(|b| *b).collect::<Vec<u8>>(), output)
302    }
303
304    #[test]
305    fn test_function_keys() {
306        let mut st = b"\x1BOP\x1BOQ\x1BOR\x1BOS".keys();
307        for i in 1..5 {
308            assert_eq!(st.next().unwrap().unwrap(), Key::F(i));
309        }
310
311        let mut st = b"\x1B[11~\x1B[12~\x1B[13~\x1B[14~\x1B[15~\
312        \x1B[17~\x1B[18~\x1B[19~\x1B[20~\x1B[21~\x1B[23~\x1B[24~"
313                .keys();
314        for i in 1..13 {
315            assert_eq!(st.next().unwrap().unwrap(), Key::F(i));
316        }
317    }
318
319    #[test]
320    fn test_special_keys() {
321        let mut st = b"\x1B[2~\x1B[H\x1B[7~\x1B[5~\x1B[3~\x1B[F\x1B[8~\x1B[6~".keys();
322        assert_eq!(st.next().unwrap().unwrap(), Key::Insert);
323        assert_eq!(st.next().unwrap().unwrap(), Key::Home);
324        assert_eq!(st.next().unwrap().unwrap(), Key::Home);
325        assert_eq!(st.next().unwrap().unwrap(), Key::PageUp);
326        assert_eq!(st.next().unwrap().unwrap(), Key::Delete);
327        assert_eq!(st.next().unwrap().unwrap(), Key::End);
328        assert_eq!(st.next().unwrap().unwrap(), Key::End);
329        assert_eq!(st.next().unwrap().unwrap(), Key::PageDown);
330        assert!(st.next().is_none());
331    }
332
333    #[test]
334    fn test_esc_key() {
335        let mut st = b"\x1B".keys();
336        assert_eq!(st.next().unwrap().unwrap(), Key::Esc);
337        assert!(st.next().is_none());
338    }
339
340    fn line_match(a: &str, b: Option<&str>) {
341        let mut sink = io::sink();
342
343        let line = a.as_bytes().read_line().unwrap();
344        let pass = a.as_bytes().read_passwd(&mut sink).unwrap();
345
346        // godammit rustc
347
348        assert_eq!(line, pass);
349
350        if let Some(l) = line {
351            assert_eq!(Some(l.as_str()), b);
352        } else {
353            assert!(b.is_none());
354        }
355    }
356
357    #[test]
358    fn test_read() {
359        let test1 = "this is the first test";
360        let test2 = "this is the second test";
361
362        line_match(test1, Some(test1));
363        line_match(test2, Some(test2));
364    }
365
366    #[test]
367    fn test_backspace() {
368        line_match("this is the\x7f first\x7f\x7f test",
369                   Some("this is th fir test"));
370        line_match("this is the seco\x7fnd test\x7f",
371                   Some("this is the secnd tes"));
372    }
373
374    #[test]
375    fn test_end() {
376        line_match("abc\nhttps://www.youtube.com/watch?v=dQw4w9WgXcQ",
377                   Some("abc"));
378        line_match("hello\rhttps://www.youtube.com/watch?v=yPYZpwSpKmA",
379                   Some("hello"));
380    }
381
382    #[test]
383    fn test_abort() {
384        line_match("abc\x03https://www.youtube.com/watch?v=dQw4w9WgXcQ", None);
385        line_match("hello\x04https://www.youtube.com/watch?v=yPYZpwSpKmA", None);
386    }
387
388}
termion/input.rs

termion/
input.rs
