1 | # ansi-escapes
|
2 |
|
3 | > [ANSI escape codes](http://www.termsys.demon.co.uk/vtansi.htm) for manipulating the terminal
|
4 |
|
5 | ## Install
|
6 |
|
7 | ```sh
|
8 | npm install ansi-escapes
|
9 | ```
|
10 |
|
11 | ## Usage
|
12 |
|
13 | ```js
|
14 | import ansiEscapes from 'ansi-escapes';
|
15 |
|
16 | // Moves the cursor two rows up and to the left
|
17 | process.stdout.write(ansiEscapes.cursorUp(2) + ansiEscapes.cursorLeft);
|
18 | //=> '\u001B[2A\u001B[1000D'
|
19 | ```
|
20 |
|
21 | **You can also use it in the browser with Xterm.js:**
|
22 |
|
23 | ```js
|
24 | import ansiEscapes from 'ansi-escapes';
|
25 | import {Terminal} from 'xterm';
|
26 | import 'xterm/css/xterm.css';
|
27 |
|
28 | const terminal = new Terminal({…});
|
29 |
|
30 | // Moves the cursor two rows up and to the left
|
31 | terminal.write(ansiEscapes.cursorUp(2) + ansiEscapes.cursorLeft);
|
32 | //=> '\u001B[2A\u001B[1000D'
|
33 | ```
|
34 |
|
35 | ## API
|
36 |
|
37 | ### cursorTo(x, y?)
|
38 |
|
39 | Set the absolute position of the cursor. `x0` `y0` is the top left of the screen.
|
40 |
|
41 | ### cursorMove(x, y?)
|
42 |
|
43 | Set the position of the cursor relative to its current position.
|
44 |
|
45 | ### cursorUp(count)
|
46 |
|
47 | Move cursor up a specific amount of rows. Default is `1`.
|
48 |
|
49 | ### cursorDown(count)
|
50 |
|
51 | Move cursor down a specific amount of rows. Default is `1`.
|
52 |
|
53 | ### cursorForward(count)
|
54 |
|
55 | Move cursor forward a specific amount of columns. Default is `1`.
|
56 |
|
57 | ### cursorBackward(count)
|
58 |
|
59 | Move cursor backward a specific amount of columns. Default is `1`.
|
60 |
|
61 | ### cursorLeft
|
62 |
|
63 | Move cursor to the left side.
|
64 |
|
65 | ### cursorSavePosition
|
66 |
|
67 | Save cursor position.
|
68 |
|
69 | ### cursorRestorePosition
|
70 |
|
71 | Restore saved cursor position.
|
72 |
|
73 | ### cursorGetPosition
|
74 |
|
75 | Get cursor position.
|
76 |
|
77 | ### cursorNextLine
|
78 |
|
79 | Move cursor to the next line.
|
80 |
|
81 | ### cursorPrevLine
|
82 |
|
83 | Move cursor to the previous line.
|
84 |
|
85 | ### cursorHide
|
86 |
|
87 | Hide cursor.
|
88 |
|
89 | ### cursorShow
|
90 |
|
91 | Show cursor.
|
92 |
|
93 | ### eraseLines(count)
|
94 |
|
95 | Erase from the current cursor position up the specified amount of rows.
|
96 |
|
97 | ### eraseEndLine
|
98 |
|
99 | Erase from the current cursor position to the end of the current line.
|
100 |
|
101 | ### eraseStartLine
|
102 |
|
103 | Erase from the current cursor position to the start of the current line.
|
104 |
|
105 | ### eraseLine
|
106 |
|
107 | Erase the entire current line.
|
108 |
|
109 | ### eraseDown
|
110 |
|
111 | Erase the screen from the current line down to the bottom of the screen.
|
112 |
|
113 | ### eraseUp
|
114 |
|
115 | Erase the screen from the current line up to the top of the screen.
|
116 |
|
117 | ### eraseScreen
|
118 |
|
119 | Erase the screen and move the cursor the top left position.
|
120 |
|
121 | ### scrollUp
|
122 |
|
123 | Scroll display up one line.
|
124 |
|
125 | ### scrollDown
|
126 |
|
127 | Scroll display down one line.
|
128 |
|
129 | ### clearScreen
|
130 |
|
131 | Clear the terminal screen. (Viewport)
|
132 |
|
133 | ### clearTerminal
|
134 |
|
135 | Clear the whole terminal, including scrollback buffer. (Not just the visible part of it)
|
136 |
|
137 | ### enterAlternativeScreen
|
138 |
|
139 | Enter the [alternative screen](https://terminalguide.namepad.de/mode/p47/).
|
140 |
|
141 | ### exitAlternativeScreen
|
142 |
|
143 | Exit the [alternative screen](https://terminalguide.namepad.de/mode/p47/), assuming `enterAlternativeScreen` was called before.
|
144 |
|
145 | ### beep
|
146 |
|
147 | Output a beeping sound.
|
148 |
|
149 | ### link(text, url)
|
150 |
|
151 | Create a clickable link.
|
152 |
|
153 | [Supported terminals.](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) Use [`supports-hyperlinks`](https://github.com/jamestalmage/supports-hyperlinks) to detect link support.
|
154 |
|
155 | ### image(filePath, options?)
|
156 |
|
157 | Display an image.
|
158 |
|
159 | *Currently only supported on iTerm2 >=3*
|
160 |
|
161 | See [term-img](https://github.com/sindresorhus/term-img) for a higher-level module.
|
162 |
|
163 | #### input
|
164 |
|
165 | Type: `Buffer`
|
166 |
|
167 | Buffer of an image. Usually read in with `fs.readFile()`.
|
168 |
|
169 | #### options
|
170 |
|
171 | Type: `object`
|
172 |
|
173 | ##### width
|
174 | ##### height
|
175 |
|
176 | Type: `string | number`
|
177 |
|
178 | The width and height are given as a number followed by a unit, or the word "auto".
|
179 |
|
180 | - `N`: N character cells.
|
181 | - `Npx`: N pixels.
|
182 | - `N%`: N percent of the session's width or height.
|
183 | - `auto`: The image's inherent size will be used to determine an appropriate dimension.
|
184 |
|
185 | ##### preserveAspectRatio
|
186 |
|
187 | Type: `boolean`\
|
188 | Default: `true`
|
189 |
|
190 | ### iTerm.setCwd(path?)
|
191 |
|
192 | Type: `string`\
|
193 | Default: `process.cwd()`
|
194 |
|
195 | [Inform iTerm2](https://www.iterm2.com/documentation-escape-codes.html) of the current directory to help semantic history and enable [Cmd-clicking relative paths](https://coderwall.com/p/b7e82q/quickly-open-files-in-iterm-with-cmd-click).
|
196 |
|
197 | ### iTerm.annotation(message, options?)
|
198 |
|
199 | Creates an escape code to display an "annotation" in iTerm2.
|
200 |
|
201 | An annotation looks like this when shown:
|
202 |
|
203 | <img src="https://user-images.githubusercontent.com/924465/64382136-b60ac700-cfe9-11e9-8a35-9682e8dc4b72.png" width="500">
|
204 |
|
205 | See the [iTerm Proprietary Escape Codes documentation](https://iterm2.com/documentation-escape-codes.html) for more information.
|
206 |
|
207 | #### message
|
208 |
|
209 | Type: `string`
|
210 |
|
211 | The message to display within the annotation.
|
212 |
|
213 | The `|` character is disallowed and will be stripped.
|
214 |
|
215 | #### options
|
216 |
|
217 | Type: `object`
|
218 |
|
219 | ##### length
|
220 |
|
221 | Type: `number`\
|
222 | Default: The remainder of the line
|
223 |
|
224 | Nonzero number of columns to annotate.
|
225 |
|
226 | ##### x
|
227 |
|
228 | Type: `number`\
|
229 | Default: Cursor position
|
230 |
|
231 | Starting X coordinate.
|
232 |
|
233 | Must be used with `y` and `length`.
|
234 |
|
235 | ##### y
|
236 |
|
237 | Type: `number`\
|
238 | Default: Cursor position
|
239 |
|
240 | Starting Y coordinate.
|
241 |
|
242 | Must be used with `x` and `length`.
|
243 |
|
244 | ##### isHidden
|
245 |
|
246 | Type: `boolean`\
|
247 | Default: `false`
|
248 |
|
249 | Create a "hidden" annotation.
|
250 |
|
251 | Annotations created this way can be shown using the "Show Annotations" iTerm command.
|
252 |
|
253 | ## Related
|
254 |
|
255 | - [ansi-styles](https://github.com/chalk/ansi-styles) - ANSI escape codes for styling strings in the terminal
|