blib/lib/Antsy.pm

filter: Statementstmt 61.6% 196 / 318 Branchbran 34.0% 15 / 44 Conditioncond 13.6% 3 / 22 MC/DCmcdc 0.0% 0 / 11 Subroutinesub 56.6% 51 / 90 Podpod 100% 38 / 38 totaltotal 57.9% 303 / 523 CC 55 SCAR 18.6
CC
55
Cov
56%
cursor_get_position
42.0
_iterm_set_cursor
30.0
_256
20.0
CRAP 6.4
↑ Summary
1 7 ▶use v5.26;
Subroutine BEGIN: called CC=1 SCAR=0.0
2  
3 package Antsy;
4 7 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 7 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 7 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 7 ▶use experimental qw(signatures);
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 7 ▶use Carp qw(carp);
Subroutine BEGIN: called CC=1 SCAR=0.0
10 7 ▶use Exporter qw(import);
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 7 our( @EXPORT, @EXPORT_OK, %EXPORT_TAGS );
13  
14 7 our $VERSION = '0.908';
15  
16 =encoding utf8
17  
18 =head1 NAME
19  
20 Antsy - Streaming ANSI escape sequences
21  
22 =head1 SYNOPSIS
23  
24 use Antsy qw(:all);
25  
26 print bold, underline, text_red, "Hello", reset_all;
27  
28 =head1 DESCRIPTION
29  
30 Subroutines to deal with ANSI terminal sequences. You can emit these
31 without knowing what's coming up.
32  
33 =head2 Yet another module?
34  
35 There are several modules that come close to this, but so far
36 everything is incomplete or requires you to know all of the upcoming
37 text ahead of time so you can use of it as an argument to a function.
38 I want to emit the sequence in a stream without knowing what's coming
39 up.
40  
41 =over 4
42  
43 =item * L<Term::ANSIColor>
44  
45 Wraps ANSI color stuff around text. This comes with Perl v5.10 and
46 later.
47  
48 =item * L<Text::ANSI::Util>
49  
50 Routines for dealing with text that contains ANSI code. For example,
51 ignore the ANSI sequences in computing length.
52  
53 =item * L<Text::ANSI::Printf>
54  
55 I don't really know what this does.
56  
57 =item * L<Term::ANSIScreen>
58  
59 =back
60  
61 =head2 Methods
62  
63 =over 4
64  
65 =item * bg_256( N )
66  
67 =item * bg_rgb
68  
69 =item * bg_black
70  
71 =item * bg_blue
72  
73 =item * bg_cyan
74  
75 =item * bg_green
76  
77 =item * bg_magenta
78  
79 =item * bg_orange
80  
81 =item * bg_red
82  
83 =item * bg_white
84  
85 =item * bg_yellow
86  
87 Make the background the named color
88  
89 =item * bg_bright_black
90  
91 =item * bg_bright_blue
92  
93 =item * bg_bright_cyan
94  
95 =item * bg_bright_green
96  
97 =item * bg_bright_magenta
98  
99 =item * bg_bright_red
100  
101 =item * bg_bright_white
102  
103 =item * bg_bright_yellow
104  
105 Make the background the named color and bright (however your terminal
106 does that).
107  
108 =item * bg_gray
109  
110 =item * bg_grey
111  
112 The same as C<bg_bright_black>, which most people call gray.
113  
114 =item * bg_default
115  
116 Go back to the terminal's default background color (SGR 49). Unlike
117 C<reset_all>, this leaves the text color and attributes alone.
118  
119 =item * blink
120  
121 Make the text blink (however your terminal does that).
122  
123 =item * rapid_blink
124  
125 Make the text blink quickly (SGR 6). Few terminals support this; most
126 treat it like C<blink> or ignore it. C<no_blink> turns off both.
127  
128 =item * bold
129  
130 Turn on bold
131  
132 =item * clear_line
133  
134 =item * clear_screen
135  
136 =item * clear_to_line_end
137  
138 =item * clear_to_line_start
139  
140 =item * clear_to_screen_end
141  
142 =item * clear_to_screen_start
143  
144 Clear the part of the screen as indicated. Each of these start at the
145 current cursor position.
146  
147 =item * conceal
148  
149 =item * hidden
150  
151 Make the text invisible (if your terminal handles that). Show it again
152 with C<reveal>.
153  
154 =item * cursor_back( [ N ] )
155  
156 =item * cursor_left( [ N ] )
157  
158 Move the cursor back (left) N positions.
159  
160 =item * cursor_column( [ N ] )
161  
162 Move the cursor to column N.
163  
164 =item * cursor_down( [ N ] )
165  
166 Move the cursor down N positions.
167  
168 =item * cursor_forward( [ N ] )
169  
170 =item * cursor_right( [ N ] )
171  
172 Move the cursor forward (right) N positions.
173  
174 =item * cursor_row( [ N ] )
175  
176 Move the cursor to row N, staying in the same column (VPA, C<CSI N d>).
177 This is the vertical version of C<cursor_column>.
178  
179 =item * cursor_home
180  
181 Move the cursor to the top left corner of the screen. This is the same
182 as C<cursor_row_column()> with no arguments.
183  
184 =item * cursor_line_start
185  
186 Move the cursor to the start of the current line. This is the same as
187 C<cursor_column(1)>.
188  
189 =item * cursor_next_line( [ N ] )
190  
191 Move the cursor down N lines, to the start of the line
192  
193 =item * cursor_previous_line( [ N ] )
194  
195 =item * cursor_prev_line( [ N ] )
196  
197 Move the cursor up N lines, to the start of the line
198  
199 =item * cursor_row_column( [ N, M ] )
200  
201 =item * cursor_position( [ N, M ] )
202  
203 Move the cursor to row N and column M. Both default to 1.
204  
205 =item * cursor_tab_back( [ N ] )
206  
207 Move the cursor back N tab stops (CBT, C<CSI N Z>).
208  
209 =item * cursor_tab_forward( [ N ] )
210  
211 Move the cursor forward N tab stops (CHT, C<CSI N I>).
212  
213 =item * cursor_up( [ N ] )
214  
215 Move the cursor up N lines.
216  
217 For these and for C<scroll_down> and C<scroll_up>, N defaults to 1.
218 Terminals treat a count of 0 as 1, so these never put a 0 in the
219 sequence. Instead, an N of 0 returns the empty string, except that
220 C<cursor_next_line(0)> and C<cursor_previous_line(0)> move to the start
221 of the current line, C<cursor_column(0)> moves to column 1, and
222 C<cursor_row(0)> moves to row 1. An N that isn't a non-negative integer
223 counts as 0.
224  
225 =item * cursor_hide
226  
227 Hide the cursor. See also C<cursor_show>.
228  
229 =item * cursor_show
230  
231 Show the cursor. See also C<cursor_hide>.
232  
233 =item * cursor_position_request
234  
235 The sequence that asks the terminal where the cursor is (DSR 6,
236 C<CSI 6n>). The terminal answers on its input, not its output, with
237 C<CSI ROW ; COLUMN R>. Use this if you read the terminal yourself;
238 otherwise use C<cursor_get_position>.
239  
240 =item * cursor_get_position( [ TIMEOUT ] )
241  
242 Ask the terminal where the cursor is, and return the row and column
243 (both starting at 1):
244  
245 my( $row, $column ) = cursor_get_position();
246  
247 This opens F</dev/tty>, puts it in raw mode, sends
248 C<cursor_position_request>, and reads the answer, so it works only on
249 Unix-like systems with a terminal. It waits up to TIMEOUT seconds
250 (default 0.5) for each character, since some terminals never answer.
251 It returns the empty list if it can't open the terminal, gets no
252 answer, or can't understand it. It needs L<Term::ReadKey>, which it
253 loads only when you call it.
254  
255 =item * dark
256  
257 Make the text dark (however your terminal does that).
258  
259 =item * erase_in_display( [ N ] )
260  
261 Erase part of the screen (ED, C<CSI N J>). The cursor doesn't move.
262 N defaults to 0:
263  
264 =over 4
265  
266 =item * 0 - from the cursor to the end of the screen
267  
268 =item * 1 - from the start of the screen to the cursor
269  
270 =item * 2 - the whole screen
271  
272 =item * 3 - the whole screen and the scrollback buffer (an xterm
273 extension that most terminals support)
274  
275 =back
276  
277 Any other value carps and returns the empty string.
278  
279 =item * erase_in_line( [ N ] )
280  
281 Erase part of the current line (EL, C<CSI N K>). The cursor doesn't
282 move. N defaults to 0:
283  
284 =over 4
285  
286 =item * 0 - from the cursor to the end of the line
287  
288 =item * 1 - from the start of the line to the cursor
289  
290 =item * 2 - the whole line
291  
292 =back
293  
294 Any other value carps and returns the empty string.
295  
296 =item * erase_line
297  
298 =item * erase_screen
299  
300 =item * erase_screen_and_scrollback
301  
302 =item * erase_to_end_of_line
303  
304 =item * erase_to_end_of_screen
305  
306 =item * erase_to_start_of_line
307  
308 =item * erase_to_start_of_screen
309  
310 Shortcuts for C<erase_in_display> and C<erase_in_line> with each of
311 their arguments, so you don't have to remember the numbers. For
312 example, C<erase_to_end_of_screen> is C<erase_in_display(0)> and
313 C<erase_line> is C<erase_in_line(2)>.
314  
315 =item * dim
316  
317 =item * faint
318  
319 The same as C<dark> (SGR 2). The standard calls this "faint" (decreased
320 intensity), and terminfo and many other tools call it "dim".
321  
322 =item * hide_cursor
323  
324 Deprecated. Use C<cursor_hide> instead.
325  
326 =item * inverse
327  
328 =item * reverse_video
329  
330 Use the background color for the text color, and the text color
331 for the background (SGR 7). Use these instead of C<reverse>, which
332 Antsy can't export.
333  
334 =item * italic
335  
336 Turn on italic.
337  
338 =item * no_blink
339  
340 Turn off blinking (SGR 25).
341  
342 =item * no_bold
343  
344 =item * no_dark
345  
346 =item * no_dim
347  
348 =item * no_faint
349  
350 =item * normal_intensity
351  
352 Turn off bold and dark (or faint) (SGR 22). These are all the same:
353 terminals have no way to turn off just one of bold and dark, so each
354 of these turns off both.
355  
356 Some terminals treat SGR 21 as "bold off", but the standard says SGR 21
357 is double underline, so Antsy doesn't use it.
358  
359 =item * no_italic
360  
361 Turn off italic (SGR 23).
362  
363 =item * no_inverse
364  
365 =item * no_reverse
366  
367 =item * no_reverse_video
368  
369 Turn off reverse video (SGR 27).
370  
371 =item * no_strikethrough
372  
373 Turn off strikethrough (SGR 29).
374  
375 =item * no_underline
376  
377 Turn off underlining (SGR 24).
378  
379 =item * normal
380  
381 =item * reset_all
382  
383 Turn off all attributes and go back to the default colors (SGR 0).
384 C<normal> is not the same as C<normal_intensity>, which only turns off
385 bold and dark.
386  
387 =item * reset
388  
389 The same as C<reset_all>, but Antsy can't export it. Importing a sub
390 named C<reset> would replace Perl's built-in C<reset> in your program,
391 so it isn't in C<@EXPORT_OK> or any export tag. Use C<reset_all> or
392 C<normal>, or call it with its full name, C<Antsy::reset()>.
393  
394 =item * reveal
395  
396 Show text hidden by C<conceal> (SGR 28).
397  
398 =item * reverse
399  
400 The same as C<inverse>, but Antsy can't export it. Importing a sub
401 named C<reverse> would replace Perl's built-in C<reverse> in your
402 program, so C<reverse @list> would stop working. It isn't in
403 C<@EXPORT_OK> or any export tag. Use C<inverse> or C<reverse_video>,
404 or call it with its full name, C<Antsy::reverse()>.
405  
406 =item * scroll_down( [ N ] )
407  
408 Scroll down N lines. See C<cursor_up> for how N works.
409  
410 =item * scroll_up( [ N ] )
411  
412 Scroll up N lines. See C<cursor_up> for how N works.
413  
414 =item * show_cursor
415  
416 Deprecated. Use C<cursor_show> instead.
417  
418 =item * strikethrough
419  
420 Draw a line through the text (SGR 9), which the standard calls
421 "crossed-out".
422  
423 =item * text_256( N )
424  
425 Make the foreground the color N in the xterm 256 color chart.
426  
427 This dies if N is not a positive number between 0 and 255 (inclusive).
428  
429 =item * text_black
430  
431 =item * text_blue
432  
433 =item * text_cyan
434  
435 =item * text_green
436  
437 =item * text_magenta
438  
439 =item * text_orange
440  
441 =item * text_red
442  
443 =item * text_rgb
444  
445 =item * text_white
446  
447 =item * text_yellow
448  
449 Make foreground text the named color.
450  
451 =item * text_bright_black
452  
453 =item * text_bright_blue
454  
455 =item * text_bright_cyan
456  
457 =item * text_bright_green
458  
459 =item * text_bright_magenta
460  
461 =item * text_bright_red
462  
463 =item * text_bright_white
464  
465 =item * text_bright_yellow
466  
467 Make foreground text the named color and bright (however your terminal
468 does that).
469  
470 =item * text_gray
471  
472 =item * text_grey
473  
474 The same as C<text_bright_black>, which most people call gray.
475  
476 =item * text_default
477  
478 Go back to the terminal's default text color (SGR 39). Unlike
479 C<reset_all>, this leaves the background color and attributes alone.
480  
481 =item * underline
482  
483 Turn on underlining.
484  
485 =back
486  
487 =head2 Saving and restoring the cursor
488  
489 Terminals have two ways to save the cursor and come back to it later:
490 the DEC way and the SCO way. Each has only one save slot, so saving
491 again replaces whatever you saved before; you can't nest them.
492  
493 The DEC versions are the ones to use. They work in essentially every
494 terminal, and they're what terminfo's C<sc> and C<rc> capabilities
495 (C<tput sc>) send for most terminals. The SCO versions are less
496 predictable: some terminals save only the position, others (such as
497 xterm and the VT510) save the same things as the DEC versions, some
498 terminals ignore them, and in terminals with left and right margins
499 turned on, C<CSI s> sets the margins instead.
500  
501 For the details, see the VT510 reference pages for
502 L<DECSC|https://vt100.net/docs/vt510-rm/DECSC.html>,
503 L<DECRC|https://vt100.net/docs/vt510-rm/DECRC.html>,
504 L<SCOSC|https://vt100.net/docs/vt510-rm/SCOSC.html>, and
505 L<SCORC|https://vt100.net/docs/vt510-rm/SCORC.html>, and
506 L<XTerm Control Sequences|https://invisible-island.net/xterm/ctlseqs/ctlseqs.html>,
507 which also covers the conflict between C<CSI s> and setting the left
508 and right margins.
509  
510 The saved position is a screen position. If the screen scrolls between
511 saving and restoring, the cursor comes back to the same row of the
512 screen, which may now show a different line.
513  
514 =over 4
515  
516 =item * cursor_save_state
517  
518 =item * cursor_save_dec
519  
520 =item * cursor_save_all
521  
522 =item * decsc
523  
524 Save the cursor position, along with the current text attributes,
525 character sets, origin mode, and a few other settings
526 (L<DECSC|https://vt100.net/docs/vt510-rm/DECSC.html>, C<ESC 7>).
527 Restore it with C<cursor_restore_state> or any of its other names.
528  
529 =item * cursor_restore_state
530  
531 =item * cursor_restore_dec
532  
533 =item * cursor_restore_all
534  
535 =item * decrc
536  
537 Put the cursor back where C<cursor_save_state> saved it, and restore
538 the attributes saved with it
539 (L<DECRC|https://vt100.net/docs/vt510-rm/DECRC.html>, C<ESC 8>).
540  
541 =item * cursor_save
542  
543 =item * cursor_save_position
544  
545 Save the cursor position the SCO way
546 (L<SCOSC|https://vt100.net/docs/vt510-rm/SCOSC.html>, C<CSI s>). What
547 else gets saved depends on the terminal. Prefer C<cursor_save_state>.
548  
549 =item * cursor_restore
550  
551 =item * cursor_restore_position
552  
553 Put the cursor back where C<cursor_save> saved it, the SCO way
554 (L<SCORC|https://vt100.net/docs/vt510-rm/SCORC.html>, C<CSI u>).
555 Prefer C<cursor_restore_state>.
556  
557 =item * save_cursor
558  
559 Deprecated. Use C<cursor_save> (the same SCO sequence) or, better,
560 C<cursor_save_state>.
561  
562 =item * restore_cursor
563  
564 Deprecated. Use C<cursor_restore> (the same SCO sequence) or, better,
565 C<cursor_restore_state>.
566  
567 =back
568  
569 =head2 Changing the cursor shape
570  
571 These use the standard DECSCUSR sequence (C<CSI N SP q>), which works
572 in xterm, iTerm2, kitty, Windows Terminal, the VTE terminals, tmux, and
573 most others. iTerm2 also has its own way, C<iterm_set_cursor_shape>,
574 which numbers the shapes differently.
575  
576 See the VT510 reference page for
577 L<DECSCUSR|https://vt100.net/docs/vt510-rm/DECSCUSR.html>, which defines
578 shapes 0 through 4, and
579 L<XTerm Control Sequences|https://invisible-island.net/xterm/ctlseqs/ctlseqs.html>,
580 which adds the bar shapes, 5 and 6.
581  
582 =over 4
583  
584 =item * cursor_shape( [ N ] )
585  
586 Set the cursor shape. N defaults to 0:
587  
588 =over 4
589  
590 =item * 0 - the terminal's default shape (usually a blinking block)
591  
592 =item * 1 - blinking block
593  
594 =item * 2 - steady block
595  
596 =item * 3 - blinking underline
597  
598 =item * 4 - steady underline
599  
600 =item * 5 - blinking bar
601  
602 =item * 6 - steady bar
603  
604 =back
605  
606 Any other value carps and returns the empty string.
607  
608 =item * cursor_shape_default
609  
610 =item * cursor_block_blinking
611  
612 =item * cursor_block
613  
614 =item * cursor_underline_blinking
615  
616 =item * cursor_underline
617  
618 =item * cursor_bar_blinking
619  
620 =item * cursor_bar
621  
622 Shortcuts for C<cursor_shape> with each argument, so you don't have to
623 remember the numbers. For example, C<cursor_bar> is C<cursor_shape(6)>.
624  
625 =back
626  
627 =cut
628  
629 0 ▶sub _256 ( $i, $n ) {
Subroutine _256: not called CC=4 SCAR=30.0
630 0 ▶ carp "Bad 256 $n" unless( int($n) == $n and $n >= 0 and $n <= 255 );
Branch: 1 branch
BranchTrueFalseTotal
unless int $n == $n and $n >= 0 and $n <= 255 0 0 0
Condition0%0/6
int $n == $n and $n >= 0 and $n <= 255
!ll&&!rl&&r
000
int $n == $n and $n >= 0
!ll&&!rl&&r
000
MC/DC0%0/3
int $n == $n and $n >= 0 and $n <= 255
int $n == $n $n >= 0 $n <= 255
Truth table0%0/4
A and B and C
A= int $n == $nB= $n >= 0C= $n <= 255
ABCresult
0XX0
10X0
1100
1111
631 0 _seq( 'm', $i, 5, $n );
632 }
633  
634 7 ▶sub _bg () { 48 } # a magic number that applies the SGR to the background
Subroutine _bg: called CC=1 SCAR=0.0
635  
636 # _erase forms an erase sequence (J for the display, K for the line).
637 # An argument that isn't allowed carps and returns the empty string,
638 # since erasing nothing is safer than erasing the wrong part.
639 73 ▶sub _erase ( $command, $n, @allowed ) {
Subroutine _erase: called CC=2 SCAR=6.9
640 73 ▶ unless( grep { $n eq $_ } @allowed ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (grep {$n eq $_;} @allowed) 6 67 73
641 6 carp "Bad erase value <$n>. Should be one of <@allowed>";
642 6 return '';
643 }
644 67 _seq( $command, $n );
645 }
646  
647 847 ▶sub _export ( $name, $tag ) {
Subroutine _export: called CC=1 SCAR=0.0
648 847 push @EXPORT_OK, $name;
649 847 push $EXPORT_TAGS{'all'}->@*, $name;
650 847 push $EXPORT_TAGS{$tag}->@*, $name;
651 }
652  
653 14 ▶sub _rgb ( $i, $r, $g, $b ) {
Subroutine _rgb: called CC=4 SCAR=17.1
654 carp "Bad RGB $r;$b;$g" unless
655 14 ▶ 3 == grep { int($_) == $_ and $_ >= 0 and $_ <= 255 }
Branch: 1 branch
BranchTrueFalseTotal
unless 3 == grep({int $_ == $_ and $_ >= 0 and $_ <= 255;} $r, $b, $g) 0 14 14
Condition33%2/6
int $_ == $_ && $_ >= 0 && $_ <= 255
!ll&&!rl&&r
0042
int $_ == $_ and $_ >= 0
!ll&&!rl&&r
0042
MC/DC0%0/3
int $_ == $_ && $_ >= 0 && $_ <= 255
int $_ == $_ $_ >= 0 $_ <= 255
Truth table25%1/4
A and B && C
A= int $_ == $_B= $_ >= 0C= $_ <= 255
ABCresult
0XX0
10X0
1100
1111
656 ( $r, $b, $g );
657  
658 14 _seq( 'm', $i, 2, $r, $g, $b );
659 }
660  
661 # _seq forms the ANSI escape sequence. There's the start, some arguments
662 # separated by `;`, then a string for the argument
663 785 ▶sub _seq ( $command, @args ) { join '', "\x1b[", join( ';', @args ), $command }
Subroutine _seq: called CC=1 SCAR=0.0
664  
665 0 ▶sub _encode_seq ( $string ) {
Subroutine _encode_seq: not called CC=1 SCAR=6.9
666 0 local $_ = $string;
667  
668 0 s/(.)/sprintf '%02X ', ord($1) /ge;
669  
670 0 s/1b /ESC /ig;
671 0 s/07 /BEL /ig;
672 0 s/31 33 33 37 /1337 /;
673  
674 0 s/([2-7A-F][0-9A-F])\x20/ chr( hex($1) ) . ' ' /ge;
675 0 $_;
676 }
677  
678 0 ▶sub _start () { "\x1b[" }
Subroutine _start: not called CC=1 SCAR=6.9
679  
680 7 ▶sub _text () { 38 } # a magic number that applies the SGR to the text
Subroutine _text: called CC=1 SCAR=0.0
681  
682 0 ▶sub bg_256 ( $n ) { _256( _bg(), $n ) }
Subroutine bg_256: not called CC=1 SCAR=6.9
Pod documented
683 7 ▶sub bg_rgb ( $r, $g, $b ) { _rgb( _bg(), $r, $g, $b ) }
Subroutine bg_rgb: called CC=1 SCAR=0.0
Pod documented
684  
685 19 ▶sub cursor_row_column ( $n = 1, $m = 1 ) { _seq( 'H', $n, $m ) }
Subroutine cursor_row_column: called CC=3 SCAR=11.0
Pod documented
686 8 ▶sub cursor_position ( $n = 1, $m = 1 ) { cursor_row_column( $n, $m ) }
Subroutine cursor_position: called CC=3 SCAR=11.0
Pod documented
687 2 ▶sub cursor_home () { cursor_row_column() }
Subroutine cursor_home: called CC=1 SCAR=0.0
Pod documented
688 2 ▶sub cursor_line_start () { _seq( 'G', 1 ) }
Subroutine cursor_line_start: called CC=1 SCAR=0.0
Pod documented
689  
690 # Device Status Report 6 asks the terminal where the cursor is. The
691 # terminal answers on its input with CSI ROW ; COLUMN R.
692 1 ▶sub cursor_position_request () { _seq( 'n', 6 ) }
Subroutine cursor_position_request: called CC=1 SCAR=0.0
Pod documented
693  
694 0 ▶sub cursor_get_position ( $timeout = 0.5 ) {
Subroutine cursor_get_position: not called CC=6 SCAR=37.4
Pod documented
695 0 state $have_readkey = eval { require Term::ReadKey };
696 0 ▶ unless( $have_readkey ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($have_readkey) 0 0 0
697 0 carp "cursor_get_position needs Term::ReadKey";
698 0 return;
699 }
700  
701 0 ▶ open my $tty, '+<', '/dev/tty' or do {
Branch: 1 branch
BranchTrueFalseTotal
open my $tty, "+<", "/dev/tty" or do { carp("cursor_get_position couldn't open /dev/tty: $!"); return } 0 0 0
702 0 carp "cursor_get_position couldn't open /dev/tty: $!";
703 0 return;
704 };
705 0 my $old = select $tty; $| = 1; select $old;
706  
707 # Raw mode, so the reply isn't echoed and arrives without a newline.
708 # Some terminals never answer, so give up after $timeout seconds
709 # without a character.
710 0 Term::ReadKey::ReadMode( 'raw', $tty );
711 0 print { $tty } cursor_position_request();
712 0 my $reply = '';
713 0 ▶ while( defined( my $char = Term::ReadKey::ReadKey( $timeout, $tty ) ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $char = Term::ReadKey::ReadKey($timeout, $tty))) 0 0 0
714 0 $reply .= $char;
715 0 ▶ last if $char eq 'R';
Branch: 1 branch
BranchTrueFalseTotal
if $char eq "R" 0 0 0
716 }
717 0 Term::ReadKey::ReadMode( 'restore', $tty );
718  
719 0 _parse_cursor_position_report( $reply );
720 }
721  
722 4 ▶sub _parse_cursor_position_report ( $reply ) {
Subroutine _parse_cursor_position_report: called CC=2 SCAR=6.9
723 4 ▶ my( $row, $column ) = $reply =~ /\e\[(\d+);(\d+)R/ or return;
Branch: 1 branch
BranchTrueFalseTotal
() = $reply =~ /\e\[(\d+);(\d+)R/u or return 2 2 4
724 2 ( $row, $column );
725 }
726  
727 41 ▶sub erase_in_display ( $n = 0 ) { _erase( 'J', $n, 0 .. 3 ) }
Subroutine erase_in_display: called CC=2 SCAR=6.9
Pod documented
728 32 ▶sub erase_in_line ( $n = 0 ) { _erase( 'K', $n, 0 .. 2 ) }
Subroutine erase_in_line: called CC=2 SCAR=6.9
Pod documented
729  
730 # Named shortcuts for each erase_in_display and erase_in_line argument,
731 # so nobody has to remember the numbers.
732 7 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=6.9
733 7 my @helpers = (
734 # NAME SUB ARG
735 [ qw( erase_to_end_of_screen erase_in_display 0 ) ],
736 [ qw( erase_to_start_of_screen erase_in_display 1 ) ],
737 [ qw( erase_screen erase_in_display 2 ) ],
738 [ qw( erase_screen_and_scrollback erase_in_display 3 ) ],
739 [ qw( erase_to_end_of_line erase_in_line 0 ) ],
740 [ qw( erase_to_start_of_line erase_in_line 1 ) ],
741 [ qw( erase_line erase_in_line 2 ) ],
742 );
743  
744 7 foreach my $helper ( @helpers ) {
745 7 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
746 49 my( $name, $sub, $n ) = @$helper;
747 49 my $value = __PACKAGE__->can( $sub )->( $n );
748 49 ▶ *{$name} = sub () { $value };
Subroutine __ANON__: called CC=1 SCAR=0.0
749 49 _export( $name, 'erase' );
750 }
751 }
752  
753 0 ▶sub text_256 ( $n ) { _256( _text(), $n ) }
Subroutine text_256: not called CC=1 SCAR=6.9
Pod documented
754 7 ▶sub text_rgb ( $r, $g, $b ) { _rgb( _text(), $r, $g, $b ) }
Subroutine text_rgb: called CC=1 SCAR=0.0
Pod documented
755  
756  
757 # This section takes the subroutines that we've already defined to
758 # adds them to the export lists.
759 7 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
760 7 my @subs = qw( bg_256 bg_rgb text_256 text_rgb
761 erase_in_display erase_in_line cursor_row_column
762 cursor_position cursor_home cursor_line_start
763 cursor_position_request cursor_get_position
764 cursor_shape
765 );
766  
767 7 push @EXPORT_OK, @subs;
768 7 push $EXPORT_TAGS{all }->@*, @subs;
769 7 push $EXPORT_TAGS{bg }->@*, grep { /\Abg_/ } @subs;
770 7 push $EXPORT_TAGS{text }->@*, grep { /\Atext_/ } @subs;
771 7 push $EXPORT_TAGS{erase }->@*, grep { /\Aerase_/ } @subs;
772 7 push $EXPORT_TAGS{cursor}->@*, grep { /\Acursor_/ } @subs;
773 }
774  
775 7 ▶BEGIN {
Subroutine BEGIN: called CC=3 SCAR=11.0
776 7 my @groups = (
777 [ qw( J screen) ],
778 [ qw( K line ) ],
779 );
780  
781 7 my @templates = ( 'clear_to_%s_end', 'clear_to_%s_start', 'clear_%s' );
782  
783 7 foreach my $group ( @groups ) {
784 7 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
785 14 foreach my $i ( 0 .. 2 ) {
786 42 my $name = sprintf $templates[$i], $group->[1];
787 42 my $value = _seq( $group->[0], $i );
788 42 ▶ *{$name} = sub () { $value };
Subroutine __ANON__: called CC=1 SCAR=0.0
789 42 _export( $name, 'clear' );
790 }
791 }
792 }
793  
794 7 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=6.9
795 # Terminals treat a count of 0 as 1, so a 0 can't go into the
796 # sequence. ZERO is what to return instead: nothing for the relative
797 # moves, column 1 for the moves that also go to the start of a line,
798 # and row 1 for the move to a row.
799 7 my $start_of_line = _seq( 'G', 1 );
800 7 my $first_row = _seq( 'd', 1 );
801  
802 7 my @groups = (
803 # EXPORT_TAG FRAGMENT COMMAND ZERO
804 [ 'cursor', 'back', 'D', '' ],
805 [ 'cursor', 'column', 'G', $start_of_line ],
806 [ 'cursor', 'down', 'B', '' ],
807 [ 'cursor', 'forward', 'C', '' ],
808 [ 'cursor', 'next_line', 'E', $start_of_line ],
809 [ 'cursor', 'previous_line', 'F', $start_of_line ],
810 [ 'cursor', 'row', 'd', $first_row ],
811 [ 'cursor', 'tab_back', 'Z', '' ],
812 [ 'cursor', 'tab_forward', 'I', '' ],
813 [ 'cursor', 'up', 'A', '' ],
814 [ 'scroll', 'down', 'T', '' ],
815 [ 'scroll', 'up', 'S', '' ],
816 # aliases
817 [ 'cursor', 'left', 'D', '' ],
818 [ 'cursor', 'right', 'C', '' ],
819 [ 'cursor', 'prev_line', 'F', $start_of_line ],
820 );
821  
822 7 foreach my $group ( @groups ) {
823 7 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
824  
825 105 my( $export_tag, $fragment, $command, $zero ) = @$group;
826 105 my $name = join '_', $export_tag, $fragment;
827  
828 105 ▶ *{$name} = sub ( $n = 1 ) {
Subroutine __ANON__: called CC=4 SCAR=13.9
829 145 ▶ $n = $n =~ /\A([0-9]+)\z/ ? $1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$n =~ /\A([0-9]+)\z/u ? : 100 45 145
830 145 ▶ return $zero if $n == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $n == 0 66 79 145
831 79 _seq( $command, $n );
832 105 };
833  
834 105 _export( $name, $export_tag );
835 }
836 }
837  
838 7 ▶BEGIN {
Subroutine BEGIN: called CC=4 SCAR=13.9
839 # Importing a sub with the same name as a Perl builtin replaces that
840 # builtin in the importing package (for example, reverse @list would
841 # call Antsy::reverse). Define these, but never export them.
842 7 my %shadows_builtin = map { $_ => 1 } qw( reset reverse );
843  
844 7 my @groups = (
845 # EXPORT_TAG SUB_NAME COMMAND ARGS
846 [ qw( control reset m 0 ) ],
847 [ qw( control reset_all m 0 ) ],
848 [ qw( control normal m 0 ) ],
849 [ qw( text bold m 1 ) ],
850 [ qw( text dark m 2 ) ],
851 [ qw( text dim m 2 ) ],
852 [ qw( text faint m 2 ) ],
853 [ qw( text italic m 3 ) ],
854 [ qw( text underline m 4 ) ],
855 [ qw( text blink m 5 ) ],
856 [ qw( text rapid_blink m 6 ) ],
857 [ qw( text reverse m 7 ) ],
858 [ qw( text inverse m 7 ) ],
859 [ qw( text reverse_video m 7 ) ],
860 [ qw( text conceal m 8 ) ],
861 [ qw( text hidden m 8 ) ],
862 [ qw( text strikethrough m 9 ) ],
863 [ qw( text normal_intensity m 22 ) ],
864 [ qw( text no_bold m 22 ) ],
865 [ qw( text no_dark m 22 ) ],
866 [ qw( text no_dim m 22 ) ],
867 [ qw( text no_faint m 22 ) ],
868 [ qw( text no_italic m 23 ) ],
869 [ qw( text no_underline m 24 ) ],
870 [ qw( text no_blink m 25 ) ],
871 [ qw( text no_reverse m 27 ) ],
872 [ qw( text no_inverse m 27 ) ],
873 [ qw( text no_reverse_video m 27 ) ],
874 [ qw( text reveal m 28 ) ],
875 [ qw( text no_strikethrough m 29 ) ],
876 [ qw( text text_default m 39 ) ],
877 [ qw( bg bg_default m 49 ) ],
878 [ qw( cursor hide_cursor l ?25 ) ],
879 [ qw( cursor show_cursor h ?25 ) ],
880 [ qw( cursor cursor_hide l ?25 ) ],
881 [ qw( cursor cursor_show h ?25 ) ],
882 );
883  
884 7 foreach my $group ( @groups ) {
885 7 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
886  
887 252 my( $export_tag, $name, $command, $n ) = @$group;
888 252 ▶ $n //= '';
Condition50%1/2
$n //= ""
l!l
2520
MC/DC0%0/1
$n //= ""
$n
Truth table50%1/2
A
A= $n
Aresult
11
00
889 252 my $value = _seq( $command, $n );
890  
891 252 ▶ *{$name} = sub () { $value };
Subroutine __ANON__: called CC=1 SCAR=0.0
892  
893 252 ▶ _export( $name, $export_tag ) unless $shadows_builtin{$name};
Branch: 1 branch
BranchTrueFalseTotal
unless $shadows_builtin{$name} 238 14 252
894 }
895 }
896  
897 # Saving and restoring the cursor. See "Saving and restoring the
898 # cursor" in the docs for the difference between the DEC and SCO
899 # versions.
900 7 ▶BEGIN {
Subroutine BEGIN: called CC=3 SCAR=11.0
901 7 my @groups = (
902 # SEQUENCE NAMES
903 [ "\x1b7", qw( cursor_save_state cursor_save_dec cursor_save_all decsc ) ], # DECSC
904 [ "\x1b8", qw( cursor_restore_state cursor_restore_dec cursor_restore_all decrc ) ], # DECRC
905 [ _seq( 's' ), qw( cursor_save cursor_save_position save_cursor ) ], # SCOSC
906 [ _seq( 'u' ), qw( cursor_restore cursor_restore_position restore_cursor ) ], # SCORC
907 );
908  
909 7 foreach my $group ( @groups ) {
910 7 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
911 28 my( $value, @names ) = @$group;
912 28 foreach my $name ( @names ) {
913 98 ▶ *{$name} = sub () { $value };
Subroutine __ANON__: called CC=1 SCAR=0.0
914 98 _export( $name, 'cursor' );
915 }
916 }
917 }
918  
919 # Changing the cursor shape with DECSCUSR (CSI N SP q). See "Changing
920 # the cursor shape" in the docs.
921 60 ▶sub cursor_shape ( $n = 0 ) {
Subroutine cursor_shape: called CC=3 SCAR=11.0
Pod documented
922 60 ▶ unless( grep { $n eq $_ } 0 .. 6 ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (grep {$n eq $_;} 0..6) 3 57 60
923 3 carp "Bad cursor shape <$n>. Should be one of <0 1 2 3 4 5 6>";
924 3 return '';
925 }
926 57 _seq( ' q', $n );
927 }
928  
929 # Named shortcuts for each cursor_shape argument.
930 7 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=6.9
931 7 my @helpers = (
932 # NAME SHAPE
933 [ qw( cursor_shape_default 0 ) ],
934 [ qw( cursor_block_blinking 1 ) ],
935 [ qw( cursor_block 2 ) ],
936 [ qw( cursor_underline_blinking 3 ) ],
937 [ qw( cursor_underline 4 ) ],
938 [ qw( cursor_bar_blinking 5 ) ],
939 [ qw( cursor_bar 6 ) ],
940 );
941  
942 7 foreach my $helper ( @helpers ) {
943 7 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
944 49 my( $name, $n ) = @$helper;
945 49 my $value = cursor_shape( $n );
946 49 ▶ *{$name} = sub () { $value };
Subroutine __ANON__: called CC=1 SCAR=0.0
947 49 _export( $name, 'cursor' );
948 }
949 }
950  
951 7 ▶BEGIN {
Subroutine BEGIN: called CC=7 SCAR=19.5
952 7 my @colors = qw( black red green yellow blue magenta cyan white );
953 7 my %colors = map { state $n = 0; $_ => $n++ } @colors;
954  
955 7 my @groups = (
956 [ qw( 30 text %s ) ],
957 [ qw( 90 text bright %s ) ],
958 [ qw( 40 bg %s ) ],
959 [ qw( 100 bg bright %s ) ],
960 );
961  
962 7 foreach my $group ( @groups ) {
963 28 my $offset = shift @$group;
964 28 my $template = join "_", @$group;
965  
966 28 foreach my $i ( 0 .. $#colors ) {
967 7 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
968 224 my $name = sprintf $template, $colors[$i];
969 224 my $value = _seq( 'm', $offset + $i );
970 224 ▶ *{$name} = sub () { $value };
Subroutine __ANON__: called CC=1 SCAR=0.0
971  
972 # The tag is text or bg. The bright colors also go in their
973 # own bright tag.
974 224 _export( $name, $group->[0] );
975 224 ▶ push $EXPORT_TAGS{bright}->@*, $name if $group->[1] eq 'bright';
Branch: 1 branch
BranchTrueFalseTotal
if $group->[1] eq "bright" 112 112 224
976 }
977 }
978  
979 # Most people call bright black gray (or grey), so give it those
980 # names too. Copy the value from the bright_black sub so they can't
981 # drift apart.
982 7 foreach my $prefix ( qw( text bg ) ) {
983 7 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
984 14 my $value = __PACKAGE__->can( "${prefix}_bright_black" )->();
985 14 foreach my $spelling ( qw( gray grey ) ) {
986 28 my $name = "${prefix}_$spelling";
987 28 ▶ *{$name} = sub () { $value };
Subroutine __ANON__: called CC=1 SCAR=0.0
988 28 _export( $name, $prefix );
989 28 push $EXPORT_TAGS{bright}->@*, $name;
990 }
991 }
992  
993 7 my @secondary_colors = (
994 [ 'orange', [ 0xFF, 0x8C, 0x00 ] ],
995 );
996  
997 7 foreach my $tuple ( @secondary_colors ) {
998 7 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
999 7 my( $color, $rgb ) = $tuple->@*;
1000  
1001 # Each sub needs its own variable to close over. If they shared
1002 # one, reassigning it would change what the other returns.
1003 7 my $text_name = "text_$color";
1004 7 my $text_value = text_rgb( $rgb->@* );
1005 7 ▶ *{$text_name} = sub () { $text_value };
Subroutine __ANON__: called CC=1 SCAR=0.0
1006 7 _export( $text_name, 'text' );
1007  
1008 7 my $bg_name = "bg_$color";
1009 7 my $bg_value = bg_rgb( $rgb->@* );
1010 7 ▶ *{$bg_name} = sub () { $bg_value };
Subroutine __ANON__: called CC=1 SCAR=0.0
1011 7 _export( $bg_name, 'bg' );
1012 }
1013 }
1014  
1015 =head2 Character shortcuts
1016  
1017 =over 4
1018  
1019 =item * BELL - \007
1020  
1021 =item * CSI - ESC [
1022  
1023 =item * ESC - \x1b
1024  
1025 =item * OSC - ESC ]
1026  
1027 =item * ST - BELL or ESC \
1028  
1029 =item * SP - literal space
1030  
1031 =back
1032  
1033 =cut
1034  
1035 0 ▶sub BELL () { "\007" }
Subroutine BELL: not called CC=1 SCAR=6.9
Pod documented
1036 0 ▶sub CSI () { ESC() . '[' }
Subroutine CSI: not called CC=1 SCAR=6.9
Pod documented
1037 0 ▶sub ESC () { "\x1b" }
Subroutine ESC: not called CC=1 SCAR=6.9
Pod documented
1038 0 ▶sub OSC () { ESC() . ']' }
Subroutine OSC: not called CC=1 SCAR=6.9
Pod documented
1039 0 ▶sub SP () { ' ' }
Subroutine SP: not called CC=1 SCAR=6.9
Pod documented
1040 0 ▶sub ST () { BELL() }
Subroutine ST: not called CC=1 SCAR=6.9
Pod documented
1041  
1042 =head2 Editor-specific codes
1043  
1044 =head3 iTerm2
1045  
1046 iTerm2 supports proprietary
1047  
1048 =over 4
1049  
1050 =item * iterm_bg_color()
1051  
1052 =item * iterm_fg_color() OSC 4 ; -1; ? ST
1053  
1054 Returns an array reference of the decimal values for the Red, Green
1055 and Blue components of the background or foreground. These triplets
1056 may be 2 or 4 digits in each component.
1057  
1058 =cut
1059  
1060 0 ▶sub _iterm_id { 'iTerm.app' }
Subroutine _iterm_id: not called CC=1 SCAR=6.9
1061  
1062 0 ▶sub _is_term_type ( $id ) {
Subroutine _is_term_type: not called CC=2 SCAR=17.9
1063 0 ▶ ( $ENV{TERM_PROGRAM} // '' ) =~ m/\A\Q$id\E\z/;
Condition0%0/2
$ENV{"TERM_PROGRAM"} // ""
l!l
00
MC/DC0%0/1
$ENV{"TERM_PROGRAM"} // ""
$ENV{"TERM_PROGRAM"}
Truth table0%0/2
A
A= $ENV{"TERM_PROGRAM"}
Aresult
11
00
1064 }
1065  
1066 0 ▶sub _is_iterm { _is_term_type( _iterm_id() ) }
Subroutine _is_iterm: not called CC=1 SCAR=6.9
1067  
1068 0 ▶sub _iterm_seq ( $command, @args ) {
Subroutine _iterm_seq: not called CC=2 SCAR=17.9
1069 0 ▶ unless( _is_iterm() ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (_is_iterm()) 0 0 0
1070 0 my $sub = ( caller(1) )[3];
1071 0 carp( "$sub only works in iTerm2" );
1072 0 return;
1073 }
1074  
1075 0 OSC() . join( ';', @args, '' ) . $command . ST();
1076 }
1077  
1078 0 ▶sub _iterm_query ( $command, @args ) {
Subroutine _iterm_query: not called CC=4 SCAR=30.0
1079 0 my $terminal = do {
1080 0 state $rc = require Term::ReadKey;
1081 0 chomp( my $tty = `/usr/bin/tty` );
1082 # say "Term: ", $tty;
1083 0 open my $terminal, '+<', $tty;
1084 0 my $old = select( $terminal );
1085 0 $|++;
1086 0 select( $old );
1087 0 $terminal;
1088 };
1089  
1090 0 print { $terminal } _iterm_seq( $command, @args );;
1091 0 Term::ReadKey::ReadMode('raw');
1092 0 my $response;
1093 my $key;
1094 0 ▶ while( defined ($key = Term::ReadKey::ReadKey(0)) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($key = Term::ReadKey::ReadKey(0))) 0 0 0
1095 0 $response .= $key;
1096 0 ▶ last if ord( $key ) == 3; # Control-C
Branch: 1 branch
BranchTrueFalseTotal
if ord $key == 3 0 0 0
1097 0 ▶ last if ord( $key ) == 7;
Branch: 1 branch
BranchTrueFalseTotal
if ord $key == 7 0 0 0
1098 }
1099 0 Term::ReadKey::ReadMode('normal');
1100  
1101 0 $response;
1102 }
1103  
1104 0 ▶sub _iterm_rgb_query ( $type ) {
Subroutine _iterm_rgb_query: not called CC=1 SCAR=6.9
1105 0 state $OSC = qr/ ( \007 | \x1b \\ ) /xn;
1106 0 my $response = _iterm_query( '?', 4, $type );
1107 0 my( $r, $g, $b ) = $response =~ m|rgb:(.+?)/(.+?)/(.+?)$OSC|;
1108 0 [ $r, $g, $b ]
1109 }
1110  
1111 0 ▶sub iterm_bg_color () { _iterm_rgb_query( -2 ) } # OSC 4 ; -2; ? ST
Subroutine iterm_bg_color: not called CC=1 SCAR=6.9
Pod documented
1112 0 ▶sub iterm_fg_color () { _iterm_rgb_query( -1 ) } # OSC 4 ; -1; ? ST
Subroutine iterm_fg_color: not called CC=1 SCAR=6.9
Pod documented
1113  
1114 =item * iterm_start_link( URL [, ID] )
1115  
1116 =item * iterm_end_link()
1117  
1118 Mark some text as a clickable URL.
1119 OSC 8 ; [params] ; [url] ST id is only param
1120  
1121 =item * iterm_linked_text( TEXT, URL, [, ID] )
1122  
1123 =cut
1124  
1125 0 ▶sub iterm_start_link ( $url, $id = undef ) {
Subroutine iterm_start_link: not called CC=3 SCAR=24.8
Pod documented
1126 0 ▶ $id = defined $id ? "id=$id" : '';
Branch: 1 branch
BranchTrueFalseTotal
defined $id ? : 0 0 0
1127 0 OSC() . 8 . ';' . $id . ';' . $url . ST();
1128 }
1129  
1130 0 ▶sub iterm_end_link () { OSC() . 8 . ';;' . ST() }
Subroutine iterm_end_link: not called CC=1 SCAR=6.9
Pod documented
1131  
1132 0 ▶sub iterm_linked_text ( $text, $url, $id = undef ) {
Subroutine iterm_linked_text: not called CC=2 SCAR=17.9
Pod documented
1133 0 iterm_start_link( $url, $id ) .
1134 $text .
1135 iterm_end_link();
1136 }
1137  
1138 =item * iterm_set_cursor_shape( N )
1139  
1140 Change the cursor shape the iTerm2 way (C<OSC 1337 ; CursorShape=N ST>):
1141  
1142 =over 4
1143  
1144 =item * 0 Block
1145  
1146 =item * 1 Vertical bar
1147  
1148 =item * 2 Underline
1149  
1150 =back
1151  
1152 Any other N carps and returns nothing. These numbers aren't the same as
1153 the standard ones that C<cursor_shape> uses, which work in iTerm2 and
1154 most other terminals; see "Changing the cursor shape".
1155  
1156 =item * iterm_set_block_cursor
1157  
1158 =item * iterm_set_bar_cursor
1159  
1160 =item * iterm_set_underline_cursor
1161  
1162 Change the cursor to a block, a vertical bar, or an underline. Like the
1163 other iTerm2 functions, these work only in iTerm2; anywhere else, they
1164 carp and return nothing.
1165  
1166 =cut
1167  
1168 0 ▶sub _osc_1337 ( $content ) {
Subroutine _osc_1337: not called CC=2 SCAR=17.9
1169 0 ▶ unless( _is_iterm() ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (_is_iterm()) 0 0 0
1170 0 my $sub = ( caller(1) )[3];
1171 0 carp( "$sub only works in iTerm2" );
1172 0 return;
1173 }
1174  
1175 0 OSC() . 1337 . ';' . $content . ST()
1176 }
1177  
1178 # OSC 1337 ; CursorShape=[N] ST
1179 0 ▶sub _iterm_set_cursor ( $n ) {
Subroutine _iterm_set_cursor: not called CC=5 SCAR=34.0
1180 0 ▶ unless( $n == 0 or $n == 1 or $n == 2 ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($n == 0 or $n == 1 or $n == 2) 0 0 0
Condition0%0/6
$n == 0 or $n == 1 or $n == 2
l!l&&r!l&&!r
000
$n == 0 or $n == 1
l!l&&r!l&&!r
000
MC/DC0%0/3
$n == 0 or $n == 1 or $n == 2
$n == 0 $n == 1 $n == 2
Truth table0%0/4
A or B or C
A= $n == 0B= $n == 1C= $n == 2
ABCresult
1XX1
01X1
0011
0000
1181 0 carp "The cursor type can be 0, 1, or 2, but you specified <$n>";
1182 0 return;
1183 }
1184  
1185 # Check here rather than leaving it to _osc_1337 so the warning
1186 # names the public function (such as iterm_set_bar_cursor) instead
1187 # of this one.
1188 0 ▶ unless( _is_iterm() ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (_is_iterm()) 0 0 0
1189 0 my $sub = ( caller(1) )[3];
1190 0 carp( "$sub only works in iTerm2" );
1191 0 return;
1192 }
1193  
1194 0 _osc_1337( "CursorShape=$n" );
1195 }
1196  
1197 0 ▶sub iterm_set_cursor_shape ( $n ) { _iterm_set_cursor( $n ) }
Subroutine iterm_set_cursor_shape: not called CC=1 SCAR=6.9
Pod documented
1198  
1199 0 ▶sub iterm_set_block_cursor () { state $s = _iterm_set_cursor(0); $s }
Subroutine iterm_set_block_cursor: not called CC=1 SCAR=6.9
Pod documented
1200 0 ▶sub iterm_set_bar_cursor () { state $s = _iterm_set_cursor(1); $s }
Subroutine iterm_set_bar_cursor: not called CC=1 SCAR=6.9
Pod documented
1201 0 ▶sub iterm_set_underline_cursor () { state $s = _iterm_set_cursor(2); $s }
Subroutine iterm_set_underline_cursor: not called CC=1 SCAR=6.9
Pod documented
1202  
1203 =item * set_mark
1204  
1205 Same as Command-Shift-M. Mark the current location and jump back to it
1206 with Command-Shift-J.
1207  
1208 =cut
1209  
1210 # OSC 1337 ; SetMark ST
1211 0 ▶sub set_mark () { state $s = _osc_1337( 'SetMark' ); $s }
Subroutine set_mark: not called CC=1 SCAR=6.9
Pod documented
1212  
1213 =item * steal_focus
1214  
1215 Bring the window to the foreground.
1216  
1217 =cut
1218  
1219 # OSC 1337 ; StealFocus ST
1220 0 ▶sub steal_focus () { state $s = _osc_1337( 'StealFocus' ); $s }
Subroutine steal_focus: not called CC=1 SCAR=6.9
Pod documented
1221  
1222 =item * clear_scrollback_history
1223  
1224 Erase the scrollback history.
1225  
1226 =cut
1227  
1228 # OSC 1337 ; ClearScrollback ST
1229 0 ▶sub clear_scrollback_history () { state $s = _osc_1337( 'ClearScrollback' ); $s }
Subroutine clear_scrollback_history: not called CC=1 SCAR=6.9
Pod documented
1230  
1231 =item * post_notification
1232  
1233 =cut
1234  
1235 # OSC 9 ; [Message content goes here] ST
1236  
1237 =item * set_current_directory
1238  
1239 =cut
1240  
1241 # OSC 1337 ; CurrentDir=[current directory] ST
1242  
1243 =item * change_profile
1244  
1245 =cut
1246  
1247 # OSC 1337 SetProfile=[new profile name] ST
1248  
1249 =item * start_copy_to_clipboard
1250  
1251 =item * end_copy_to_clipboard
1252  
1253 =cut
1254  
1255 # OSC 1337 ; CopyToClipboard=[clipboard name] ST
1256 # OSC 1337 ; EndCopy ST
1257  
1258 =item * change_color_palette
1259  
1260 [key] gives the color to change. The accepted values are: fg bg bold link selbg selfg curbg curfg underline tab" black red green yellow blue magenta cyan white br_black br_red br_green br_yellow br_blue br_magenta br_cyan br_white
1261  
1262 [value] gives the new color. The following formats are accepted:
1263  
1264 RGB (three hex digits, like fff)
1265 RRGGBB (six hex digits, like f0f0f0)
1266 cs:RGB (like RGB but cs gives a color space)
1267 cs:RRGGBB (like RRGGBB but cs gives a color space)
1268 If a color space is given, it should be one of:
1269  
1270 srgb (the standard sRGB color space)
1271 rgb (the device-specific color space)
1272 p3 (the standard P3 color space, whose gamut is supported on some newer hardware)
1273  
1274 =cut
1275  
1276 # OSC 1337 ; SetColors=[key]=[value] ST
1277  
1278  
1279 =item * add_annotation
1280  
1281 OSC 1337 ; AddAnnotation=[message] ST
1282 OSC 1337 ; AddAnnotation=[length] | [message] ST
1283 OSC 1337 ; AddAnnotation=[message] | [length] | [x-coord] | [y-coord] ST
1284 OSC 1337 ; AddHiddenAnnotation=[message] ST
1285 OSC 1337 ; AddHiddenAnnotation=[length] | [message] ST
1286 OSC 1337 ; AddHiddenAnnotation=[message] | [length] | [x-coord] | [y-coord] ST
1287 `[message]`: The message to attach to the annotation.
1288 `[length]`: The number of cells to annotate. Defaults to the rest of the line beginning at the start of the annotation.
1289 `[x-coord]` and `[y-coord]`: The starting coordinate for the annotation. Defaults to the cursor's coordinate.
1290  
1291 =cut
1292  
1293 sub add_annotation () {}
1294  
1295 =item * hide_cursor_guide
1296  
1297 =item * show_cursor_guide
1298  
1299 =cut
1300  
1301 # OSC 1337 ; HighlightCursorLine=[boolean] ST
1302 0 ▶sub hide_cursor_guide () { state $s = _osc_1337( 'HighlightCursorLine=no' ); $s }
Subroutine hide_cursor_guide: not called CC=1 SCAR=6.9
Pod documented
1303 0 ▶sub show_cursor_guide () { state $s = _osc_1337( 'HighlightCursorLine=yes' ); $s }
Subroutine show_cursor_guide: not called CC=1 SCAR=6.9
Pod documented
1304  
1305 =item * iterm_attention
1306  
1307 Play with the dock icon.
1308  
1309 =over 4
1310  
1311 =item * fireworks - animation at the cursor
1312  
1313 =item * no - stop bouncing the dock icon
1314  
1315 =item * once - bounce the dock icon once
1316  
1317 =item * yes - bounce the dock indefinitely
1318  
1319 =back
1320  
1321 =cut
1322  
1323 =item * iterm_bounce_dock_icon
1324  
1325 Bounce the Dock icon, continuously
1326  
1327 =item * iterm_bounce_dock_icon_once
1328  
1329 Bounce the Dock icon, only once
1330  
1331 =item * iterm_unbounce_dock_icon
1332  
1333 Stop bouncing the Dock icon
1334  
1335 =item * iterm_fireworks
1336  
1337 Show animated fireworks.
1338  
1339 =cut
1340  
1341  
1342 # OSC 1337 ; RequestAttention=[value] ST
1343 0 ▶sub iterm_attention ( $value ) {
Subroutine iterm_attention: not called CC=2 SCAR=17.9
Pod documented
1344 0 state $allowed = do {
1345 0 my %hash = map { $_, 1 } qw( fireworks no once yes );
1346 0 \%hash;
1347 };
1348 0 ▶ unless( exists $allowed->{$value} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $allowed->{$value}) 0 0 0
1349 0 carp "iterm_attention argument can be one of <@{[ join ',', sort keys %$allowed ]}>, but you specified <$value>";
1350 0 return;
1351 }
1352  
1353 0 _osc_1337( "RequestAttention=$value" );
1354 }
1355 0 ▶sub iterm_bounce_dock_icon { iterm_attention( 'yes' ) }
Subroutine iterm_bounce_dock_icon: not called CC=1 SCAR=6.9
Pod documented
1356 0 ▶sub iterm_bounce_dock_icon_once { iterm_attention( 'once' ) }
Subroutine iterm_bounce_dock_icon_once: not called CC=1 SCAR=6.9
Pod documented
1357 0 ▶sub iterm_unbounce_dock_icon { iterm_attention( 'no' ) }
Subroutine iterm_unbounce_dock_icon: not called CC=1 SCAR=6.9
Pod documented
1358 0 ▶sub iterm_fireworks { iterm_attention( 'fireworks' ) }
Subroutine iterm_fireworks: not called CC=1 SCAR=6.9
Pod documented
1359  
1360 =item * background_image_file
1361  
1362 OSC 1337 ; SetBackgroundImageFile=[base64] ST
1363 The value of [base64] is a base64-encoded filename to display as a background image. If it is an empty string then the background image will be removed. User confirmation is required as a security measure.
1364  
1365 =item * report_cell_cell
1366  
1367 OSC 1337 ; ReportCellSize ST
1368 The terminal responds with either:
1369  
1370 OSC 1337 ; ReportCellSize=[height];[width] ST
1371 Or, in newer versions:
1372  
1373 OSC 1337 ; ReportCellSize=[height];[width];[scale] ST
1374 [scale] gives the number of pixels (physical units) to points (logical units). 1.0 means non-retina, 2.0 means retina. It could take other values in the future.
1375  
1376 [height] and [width] are floating point values giving the size in points of a single character cell. For example:
1377  
1378 OSC 1337 ; ReportCellSize=17.50;8.00;2.0 ST
1379  
1380 =item * copy_to_pasteboard
1381  
1382 You can place a string in the system's pasteboard with this sequence:
1383  
1384 OSC 1337 ; Copy=:[base64] ST
1385 Where [base64] is the base64-encoded string to copy to the pasteboard.
1386  
1387 =item * report_variable
1388  
1389 Each iTerm2 session has internal variables (as described in Scripting Fundamentals). This escape sequence reports a variable's value:
1390  
1391 OSC 1337 ; ReportVariable=[base64] ST
1392 Where [base64] is a base64-encoded variable name, like session.name. It responds with:
1393  
1394 OSC 1337 ; ReportVariable=[base64] ST
1395 Where [base64] is a base64-encoded value.
1396  
1397 https://iterm2.com/documentation-scripting-fundamentals.html
1398  
1399 =item * badge
1400  
1401 The badge may be set with the following control sequence:
1402  
1403 https://iterm2.com/documentation-badges.html
1404  
1405 OSC 1337 ; SetBadgeFormat=Base-64 encoded badge format ST
1406 Here's an example that works in bash:
1407  
1408 # Set badge to show the current session name and git branch, if any is set.
1409 printf "\e]1337;SetBadgeFormat=%s\a" \
1410 $(echo -n "\(session.name) \(user.gitBranch)" | base64)
1411  
1412 =item * downloads
1413  
1414 https://iterm2.com/documentation-images.html
1415  
1416 The width and height are given as a number followed by a unit, or the word "auto".
1417  
1418 iTerm2 extends the xterm protocol with a set of proprietary escape sequences. In general, the pattern is:
1419  
1420 ESC ] 1337 ; key = value ^G
1421 Whitespace is shown here for ease of reading: in practice, no spaces should be used.
1422  
1423 For file transfer and inline images, the code is:
1424  
1425 ESC ] 1337 ; File = [arguments] : base-64 encoded file contents ^G
1426 The arguments are formatted as key=value with a semicolon between each key-value pair. They are described below:
1427  
1428 Key Description of value
1429 name base-64 encoded filename. Defaults to "Unnamed file".
1430 size File size in bytes. The file transfer will be canceled if this size is exceeded.
1431 width Optional. Width to render. See notes below.
1432 height Optional. Height to render. See notes below.
1433 preserveAspectRatio Optional. If set to 0, then the image's inherent aspect ratio will not be respected; otherwise, it will fill the specified width and height as much as possible without stretching. Defaults to 1.
1434 inline Optional. If set to 1, the file will be displayed inline. Otherwise, it will be downloaded with no visual representation in the terminal session. Defaults to 0.
1435 N: N character cells.
1436 Npx: N pixels.
1437 N%: N percent of the session's width or height.
1438 auto: The image's inherent size will be used to determine an appropriate dimension.
1439 More on File Transfers
1440 By omitting the inline argument (or setting its value to 0), files will be downloaded and saved in the Downloads folder instead of being displayed inline. Any kind of file may be downloaded, but only images will display inline. Any image format that macOS supports will display inline, including PDF, PICT, EPS, or any number of bitmap data formats (PNG, GIF, etc.). A new menu item titled Downloads will be added to the menu bar after a download begins, where progress can be monitored and the file can be located, opened, or removed.
1441  
1442 If the file's size exceeds the declared size, the transfer may be canceled. This is a security measure to prevent a download gone wrong from using unbounded memory.
1443  
1444 =item * uploads
1445  
1446 To request the user select one or more files to upload, send:
1447  
1448 OSC 1337 ; RequestUpload=format=[type] ST
1449 In the future the [type] may be configurable, but for now it must always be tgz, which is a tar and gzipped file.
1450  
1451 When iTerm2 receives this it will respond with a status of ok or abort followed by a newline. If the status is ok then it will be followed by a base-64 encoded tar.gz file.
1452  
1453 If the user selects multiple files they will be placed in a directory within the tar file.
1454  
1455 =item * set_touchbar_key_levels
1456  
1457 You can configure touch bar key labels for function keys and for the "status" button. The code used is:
1458  
1459 OSC 1337 ; SetKeyLabel=[key]=[value] ST
1460 Where [key] is one of F1, F2, ..., F24, to adjust a function key label; or it can be status to adjust the touch bar status button. You can also save and restore sets of key labels using a stack. To push the current key labels on the stack use:
1461  
1462 OSC 1337 ; PushKeyLabels ST
1463 To pop them:
1464  
1465 OSC 1337 ; PopKeyLabels ST
1466 You can optionally label the entry in the stack when you push so that pop will pop multiple sets of key labels if needed. This is useful if a program crashes or an ssh session exits unexpectedly. The corresponding codes with labels are:
1467  
1468 OSC 1337 ; PushKeyLabels=[label] ST
1469 OSC 1337 ; PopKeyLabels=[label] ST
1470 Where [label] is an ASCII string that works best if it is unique in the stack.
1471  
1472 =item * unicode_version
1473  
1474 iTerm2 by default uses Unicode 9's width tables. The user can opt to use Unicode 8's tables with a preference (for backward compatibility with older locale databases). Since not all apps will be updated at the same time, you can tell iTerm2 to use a particular set of width tables with:
1475  
1476 OSC 1337 ; UnicodeVersion=[n] ST
1477 Where [n] is 8 or 9
1478  
1479 You can push the current value on a stack and pop it off to return to the previous value by setting n to push or pop. Optionally, you may affix a label after push by setting n to something like push mylabel. This attaches a label to that stack entry. When you pop the same label, entries will be popped until that one is found. Set n to pop mylabel to effect this. This is useful if a program crashes or an ssh session ends unexpectedly.
1480  
1481 =back
1482  
1483 =head1 SEE ALSO
1484  
1485 =over 4
1486  
1487 =item * Everything you never wanted to know about ANSI escape codes https://notes.burke.libbey.me/ansi-escape-codes/
1488  
1489 =item * https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797
1490  
1491 =item * iTerm2 ANSI codes https://iterm2.com/documentation-escape-codes.html
1492  
1493 =back
1494  
1495 =head1 SOURCE AVAILABILITY
1496  
1497 This source is in Github:
1498  
1499 http://github.com/briandfoy/antsy
1500  
1501 =head1 AUTHOR
1502  
1503 brian d foy, C<< <briandfoy@pobox.com> >>
1504  
1505 =head1 COPYRIGHT AND LICENSE
1506  
1507 Copyright © 2021-2026, brian d foy, All Rights Reserved.
1508  
1509 You may redistribute this under the terms of the Artistic License 2.0.
1510  
1511 =cut
1512  
1513 7 1;
↑ Summary