1//! A terminal cursor related ANSI escape sequences.
2
3sequence!(
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
27sequence!(
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
51sequence!(
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
69sequence!(
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
87sequence!(
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
106sequence!(
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
125sequence!(
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
146sequence!(
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
163sequence!(
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
180sequence!(
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
197sequence!(
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
214sequence!(
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
241sequence!(
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
268sequence!(
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
290sequence!(
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)]
306test_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