1 //! A terminal cursor related ANSI escape sequences.
2 
3 sequence!(
4     /// Saves the cursor position.
5     ///
6     /// Use the [`RestoreCursorPosition`](struct.RestoreCursorPosition.html) sequence to
7     /// restore the cursor position.
8     ///
9     /// # Examples
10     ///
11     /// ```no_run
12     /// use std::io::{stdout, Write};
13     /// use anes::{SaveCursorPosition, RestoreCursorPosition};
14     ///
15     /// let mut stdout = stdout();
16     /// // Save cursor position
17     /// write!(stdout, "{}", SaveCursorPosition);
18     ///
19     /// // Your app
20     ///
21     /// // Restore cursor position
22     /// write!(stdout, "{}", RestoreCursorPosition);
23     /// ```
24     struct SaveCursorPosition => esc!("7")
25 );
26 
27 sequence!(
28     /// Restores the cursor position.
29     ///
30     /// Use the [`SaveCursorPosition`](struct.SaveCursorPosition.html) sequence to
31     /// save the cursor position.
32     ///
33     /// # Examples
34     ///
35     /// ```no_run
36     /// use std::io::{stdout, Write};
37     /// use anes::{SaveCursorPosition, RestoreCursorPosition};
38     ///
39     /// let mut stdout = stdout();
40     /// // Save cursor position
41     /// write!(stdout, "{}", SaveCursorPosition);
42     ///
43     /// // Your app
44     ///
45     /// // Restore cursor position
46     /// write!(stdout, "{}", RestoreCursorPosition);
47     /// ```
48     struct RestoreCursorPosition => esc!("8")
49 );
50 
51 sequence!(
52     /// Hides the cursor.
53     ///
54     /// Use the [`ShowCursor`](struct.ShowCursor.html) sequence to show the cursor.
55     ///
56     /// # Examples
57     ///
58     /// ```no_run
59     /// use std::io::{stdout, Write};
60     /// use anes::HideCursor;
61     ///
62     /// let mut stdout = stdout();
63     /// // Hide cursor
64     /// write!(stdout, "{}", HideCursor);
65     /// ```
66     struct HideCursor => csi!("?25l")
67 );
68 
69 sequence!(
70     /// Shows the cursor.
71     ///
72     /// Use the [`HideCursor`](struct.HideCursor.html) sequence to hide the cursor.
73     ///
74     /// # Examples
75     ///
76     /// ```no_run
77     /// use std::io::{stdout, Write};
78     /// use anes::ShowCursor;
79     ///
80     /// let mut stdout = stdout();
81     /// // Show cursor
82     /// write!(stdout, "{}", ShowCursor);
83     /// ```
84     struct ShowCursor => csi!("?25h")
85 );
86 
87 sequence!(
88     /// Enables the cursor blinking.
89     ///
90     /// Use the [`DisableCursorBlinking`](struct.DisableCursorBlinking.html) sequence to disable
91     /// cursor blinking.
92     ///
93     /// # Examples
94     ///
95     /// ```no_run
96     /// use std::io::{stdout, Write};
97     /// use anes::EnableCursorBlinking;
98     ///
99     /// let mut stdout = stdout();
100     /// // Enable cursor blinking
101     /// write!(stdout, "{}", EnableCursorBlinking);
102     /// ```
103     struct EnableCursorBlinking => csi!("?12h")
104 );
105 
106 sequence!(
107     /// Disables the cursor blinking.
108     ///
109     /// Use the [`EnableCursorBlinking`](struct.EnableCursorBlinking.html) sequence to enable
110     /// cursor blinking.
111     ///
112     /// # Examples
113     ///
114     /// ```no_run
115     /// use std::io::{stdout, Write};
116     /// use anes::DisableCursorBlinking;
117     ///
118     /// let mut stdout = stdout();
119     /// // Disable cursor blinking
120     /// write!(stdout, "{}", DisableCursorBlinking);
121     /// ```
122     struct DisableCursorBlinking => csi!("?12l")
123 );
124 
125 sequence!(
126     /// Moves the cursor to the given location (column, row).
127     ///
128     /// # Notes
129     ///
130     /// Top/left cell is represented as `1, 1` (`column, row`).
131     ///
132     /// # Examples
133     ///
134     /// ```no_run
135     /// use std::io::{stdout, Write};
136     /// use anes::MoveCursorTo;
137     ///
138     /// let mut stdout = stdout();
139     /// // Move cursor to top left cell
140     /// write!(stdout, "{}", MoveCursorTo(1, 1));
141     /// ```
142     struct MoveCursorTo(u16, u16) =>
143     |this, f| write!(f, csi!("{};{}H"), this.1, this.0)
144 );
145 
146 sequence!(
147     /// Moves the cursor up by the given number of rows.
148     ///
149     /// # Examples
150     ///
151     /// ```no_run
152     /// use std::io::{stdout, Write};
153     /// use anes::MoveCursorUp;
154     ///
155     /// let mut stdout = stdout();
156     /// // Move cursor up by 5 rows
157     /// write!(stdout, "{}", MoveCursorUp(5));
158     /// ```
159     struct MoveCursorUp(u16) =>
160     |this, f| write!(f, csi!("{}A"), this.0)
161 );
162 
163 sequence!(
164     /// Moves the cursor down by the given number of rows.
165     ///
166     /// # Examples
167     ///
168     /// ```no_run
169     /// use std::io::{stdout, Write};
170     /// use anes::MoveCursorDown;
171     ///
172     /// let mut stdout = stdout();
173     /// // Move cursor down by 5 rows
174     /// write!(stdout, "{}", MoveCursorDown(5));
175     /// ```
176     struct MoveCursorDown(u16) =>
177     |this, f| write!(f, csi!("{}B"), this.0)
178 );
179 
180 sequence!(
181     /// Moves the cursor right by the given number of columns.
182     ///
183     /// # Examples
184     ///
185     /// ```no_run
186     /// use std::io::{stdout, Write};
187     /// use anes::MoveCursorRight;
188     ///
189     /// let mut stdout = stdout();
190     /// // Move cursor right by 5 columns
191     /// write!(stdout, "{}", MoveCursorRight(5));
192     /// ```
193     struct MoveCursorRight(u16) =>
194     |this, f| write!(f, csi!("{}C"), this.0)
195 );
196 
197 sequence!(
198     /// Moves the cursor left by the given number of columns.
199     ///
200     /// # Examples
201     ///
202     /// ```no_run
203     /// use std::io::{stdout, Write};
204     /// use anes::MoveCursorLeft;
205     ///
206     /// let mut stdout = stdout();
207     /// // Move cursor left by 5 columns
208     /// write!(stdout, "{}", MoveCursorLeft(5));
209     /// ```
210     struct MoveCursorLeft(u16) =>
211     |this, f| write!(f, csi!("{}D"), this.0)
212 );
213 
214 sequence!(
215     /// Moves the cursor to beginning of line the given number of lines down.
216     ///
217     /// # Examples
218     ///
219     /// ```no_run
220     /// use std::io::{stdout, Write};
221     /// use anes::MoveCursorToNextLine;
222     ///
223     /// let mut stdout = stdout();
224     /// // Move cursor down by 2 rows and the move it to the first column
225     /// write!(stdout, "{}", MoveCursorToNextLine(2));
226     /// ```
227     ///
228     /// The previous example does the same thing as the following one:
229     ///
230     /// ```no_run
231     /// use std::io::{stdout, Write};
232     /// use anes::{MoveCursorDown, MoveCursorToColumn};
233     ///
234     /// let mut stdout = stdout();
235     /// write!(stdout, "{}{}", MoveCursorDown(2), MoveCursorToColumn(1));
236     /// ```
237     struct MoveCursorToNextLine(u16) =>
238     |this, f| write!(f, csi!("{}E"), this.0)
239 );
240 
241 sequence!(
242     /// Moves the cursor to beginning of line the given number of lines up.
243     ///
244     /// # Examples
245     ///
246     /// ```no_run
247     /// use std::io::{stdout, Write};
248     /// use anes::MoveCursorToPreviousLine;
249     ///
250     /// let mut stdout = stdout();
251     /// // Move cursor up by 2 rows and the move it to the first column
252     /// write!(stdout, "{}", MoveCursorToPreviousLine(2));
253     /// ```
254     ///
255     /// The previous example does the same thing as the following one:
256     ///
257     /// ```no_run
258     /// use std::io::{stdout, Write};
259     /// use anes::{MoveCursorUp, MoveCursorToColumn};
260     ///
261     /// let mut stdout = stdout();
262     /// write!(stdout, "{}{}", MoveCursorUp(2), MoveCursorToColumn(1));
263     /// ```
264     struct MoveCursorToPreviousLine(u16) =>
265     |this, f| write!(f, csi!("{}F"), this.0)
266 );
267 
268 sequence!(
269     /// Moves the cursor to the given column.
270     ///
271     /// # Notes
272     ///
273     /// Beginning of the line (left cell) is represented as `1`.
274     ///
275     /// # Examples
276     ///
277     /// ```no_run
278     /// use std::io::{stdout, Write};
279     /// use anes::MoveCursorToColumn;
280     ///
281     /// let mut stdout = stdout();
282     /// // Move cursor to the 10th column (same row)
283     /// write!(stdout, "{}", MoveCursorToColumn(10));
284     /// ```
285     struct MoveCursorToColumn(u16) =>
286     |this, f| write!(f, csi!("{}G"), this.0)
287 );
288 
289 // TODO Enhance example with Parser to show how to retrieve it
290 sequence!(
291     /// Asks for the current cursor position.
292     ///
293     /// # Examples
294     ///
295     /// ```no_run
296     /// use std::io::{stdout, Write};
297     /// use anes::ReportCursorPosition;
298     ///
299     /// let mut stdout = stdout();
300     /// write!(stdout, "{}", ReportCursorPosition);
301     /// ```
302     struct ReportCursorPosition => csi!("6n")
303 );
304 
305 #[cfg(test)]
306 test_sequences!(
307     save_cursor_position(
308         SaveCursorPosition => "\x1B7",
309     ),
310     restore_cursor_position(
311         RestoreCursorPosition => "\x1B8",
312     ),
313     hide_cursor(
314         HideCursor => "\x1B[?25l",
315     ),
316     show_cursor(
317         ShowCursor => "\x1B[?25h",
318     ),
319     disable_cursor_blinking(
320         DisableCursorBlinking => "\x1B[?12l",
321     ),
322     enable_cursor_blinking(
323         EnableCursorBlinking => "\x1B[?12h",
324     ),
325     move_cursor_up(
326         MoveCursorUp(10) => "\x1B[10A",
327     ),
328     move_cursor_down(
329         MoveCursorDown(10) => "\x1B[10B",
330     ),
331     move_cursor_right(
332         MoveCursorRight(10) => "\x1B[10C",
333     ),
334     move_cursor_left(
335         MoveCursorLeft(10) => "\x1B[10D",
336     ),
337     move_cursor_to(
338         MoveCursorTo(5, 10) => "\x1B[10;5H",
339     ),
340     move_cursor_to_next_line(
341         MoveCursorToNextLine(5) => "\x1B[5E",
342     ),
343     move_cursor_to_previous_line(
344         MoveCursorToPreviousLine(5) => "\x1B[5F",
345     ),
346     move_cursor_to_column(
347         MoveCursorToColumn(1) => "\x1B[1G",
348     ),
349     report_cursor_position(
350         ReportCursorPosition => "\x1B[6n",
351     )
352 );
353