/ 
Antsy-0.908
⭐ Starred 2 / Antsy

NAME

Antsy - Streaming ANSI escape sequences

SYNOPSIS

use Antsy qw(:all);

print bold, underline, text_red, "Hello", reset_all;

DESCRIPTION

Subroutines to deal with ANSI terminal sequences. You can emit these without knowing what's coming up.

Yet another module?

There are several modules that come close to this, but so far everything is incomplete or requires you to know all of the upcoming text ahead of time so you can use of it as an argument to a function. I want to emit the sequence in a stream without knowing what's coming up.

Methods

  • bg_256( N )

  • bg_rgb

  • bg_black

  • bg_blue

  • bg_cyan

  • bg_green

  • bg_magenta

  • bg_orange

  • bg_red

  • bg_white

  • bg_yellow

    Make the background the named color

  • bg_bright_black

  • bg_bright_blue

  • bg_bright_cyan

  • bg_bright_green

  • bg_bright_magenta

  • bg_bright_red

  • bg_bright_white

  • bg_bright_yellow

    Make the background the named color and bright (however your terminal does that).

  • bg_gray

  • bg_grey

    The same as bg_bright_black, which most people call gray.

  • bg_default

    Go back to the terminal's default background color (SGR 49). Unlike reset_all, this leaves the text color and attributes alone.

  • blink

    Make the text blink (however your terminal does that).

  • rapid_blink

    Make the text blink quickly (SGR 6). Few terminals support this; most treat it like blink or ignore it. no_blink turns off both.

  • bold

    Turn on bold

  • clear_line

  • clear_screen

  • clear_to_line_end

  • clear_to_line_start

  • clear_to_screen_end

  • clear_to_screen_start

    Clear the part of the screen as indicated. Each of these start at the current cursor position.

  • conceal

  • hidden

    Make the text invisible (if your terminal handles that). Show it again with reveal.

  • cursor_back( [ N ] )

  • cursor_left( [ N ] )

    Move the cursor back (left) N positions.

  • cursor_column( [ N ] )

    Move the cursor to column N.

  • cursor_down( [ N ] )

    Move the cursor down N positions.

  • cursor_forward( [ N ] )

  • cursor_right( [ N ] )

    Move the cursor forward (right) N positions.

  • cursor_row( [ N ] )

    Move the cursor to row N, staying in the same column (VPA, CSI N d). This is the vertical version of cursor_column.

  • cursor_home

    Move the cursor to the top left corner of the screen. This is the same as cursor_row_column() with no arguments.

  • cursor_line_start

    Move the cursor to the start of the current line. This is the same as cursor_column(1).

  • cursor_next_line( [ N ] )

    Move the cursor down N lines, to the start of the line

  • cursor_previous_line( [ N ] )

  • cursor_prev_line( [ N ] )

    Move the cursor up N lines, to the start of the line

  • cursor_row_column( [ N, M ] )

  • cursor_position( [ N, M ] )

    Move the cursor to row N and column M. Both default to 1.

  • cursor_tab_back( [ N ] )

    Move the cursor back N tab stops (CBT, CSI N Z).

  • cursor_tab_forward( [ N ] )

    Move the cursor forward N tab stops (CHT, CSI N I).

  • cursor_up( [ N ] )

    Move the cursor up N lines.

    For these and for scroll_down and scroll_up, N defaults to 1. Terminals treat a count of 0 as 1, so these never put a 0 in the sequence. Instead, an N of 0 returns the empty string, except that cursor_next_line(0) and cursor_previous_line(0) move to the start of the current line, cursor_column(0) moves to column 1, and cursor_row(0) moves to row 1. An N that isn't a non-negative integer counts as 0.

  • cursor_hide

    Hide the cursor. See also cursor_show.

  • cursor_show

    Show the cursor. See also cursor_hide.

  • cursor_position_request

    The sequence that asks the terminal where the cursor is (DSR 6, CSI 6n). The terminal answers on its input, not its output, with CSI ROW ; COLUMN R. Use this if you read the terminal yourself; otherwise use cursor_get_position.

  • cursor_get_position( [ TIMEOUT ] )

    Ask the terminal where the cursor is, and return the row and column (both starting at 1):

    my( $row, $column ) = cursor_get_position();

    This opens /dev/tty, puts it in raw mode, sends cursor_position_request, and reads the answer, so it works only on Unix-like systems with a terminal. It waits up to TIMEOUT seconds (default 0.5) for each character, since some terminals never answer. It returns the empty list if it can't open the terminal, gets no answer, or can't understand it. It needs Term::ReadKey, which it loads only when you call it.

  • dark

    Make the text dark (however your terminal does that).

  • erase_in_display( [ N ] )

    Erase part of the screen (ED, CSI N J). The cursor doesn't move. N defaults to 0:

    • 0 - from the cursor to the end of the screen

    • 1 - from the start of the screen to the cursor

    • 2 - the whole screen

    • 3 - the whole screen and the scrollback buffer (an xterm extension that most terminals support)

    Any other value carps and returns the empty string.

  • erase_in_line( [ N ] )

    Erase part of the current line (EL, CSI N K). The cursor doesn't move. N defaults to 0:

    • 0 - from the cursor to the end of the line

    • 1 - from the start of the line to the cursor

    • 2 - the whole line

    Any other value carps and returns the empty string.

  • erase_line

  • erase_screen

  • erase_screen_and_scrollback

  • erase_to_end_of_line

  • erase_to_end_of_screen

  • erase_to_start_of_line

  • erase_to_start_of_screen

    Shortcuts for erase_in_display and erase_in_line with each of their arguments, so you don't have to remember the numbers. For example, erase_to_end_of_screen is erase_in_display(0) and erase_line is erase_in_line(2).

  • dim

  • faint

    The same as dark (SGR 2). The standard calls this "faint" (decreased intensity), and terminfo and many other tools call it "dim".

  • hide_cursor

    Deprecated. Use cursor_hide instead.

  • inverse

  • reverse_video

    Use the background color for the text color, and the text color for the background (SGR 7). Use these instead of reverse, which Antsy can't export.

  • italic

    Turn on italic.

  • no_blink

    Turn off blinking (SGR 25).

  • no_bold

  • no_dark

  • no_dim

  • no_faint

  • normal_intensity

    Turn off bold and dark (or faint) (SGR 22). These are all the same: terminals have no way to turn off just one of bold and dark, so each of these turns off both.

    Some terminals treat SGR 21 as "bold off", but the standard says SGR 21 is double underline, so Antsy doesn't use it.

  • no_italic

    Turn off italic (SGR 23).

  • no_inverse

  • no_reverse

  • no_reverse_video

    Turn off reverse video (SGR 27).

  • no_strikethrough

    Turn off strikethrough (SGR 29).

  • no_underline

    Turn off underlining (SGR 24).

  • normal

  • reset_all

    Turn off all attributes and go back to the default colors (SGR 0). normal is not the same as normal_intensity, which only turns off bold and dark.

  • reset

    The same as reset_all, but Antsy can't export it. Importing a sub named reset would replace Perl's built-in reset in your program, so it isn't in @EXPORT_OK or any export tag. Use reset_all or normal, or call it with its full name, Antsy::reset().

  • reveal

    Show text hidden by conceal (SGR 28).

  • reverse

    The same as inverse, but Antsy can't export it. Importing a sub named reverse would replace Perl's built-in reverse in your program, so reverse @list would stop working. It isn't in @EXPORT_OK or any export tag. Use inverse or reverse_video, or call it with its full name, Antsy::reverse().

  • scroll_down( [ N ] )

    Scroll down N lines. See cursor_up for how N works.

  • scroll_up( [ N ] )

    Scroll up N lines. See cursor_up for how N works.

  • show_cursor

    Deprecated. Use cursor_show instead.

  • strikethrough

    Draw a line through the text (SGR 9), which the standard calls "crossed-out".

  • text_256( N )

    Make the foreground the color N in the xterm 256 color chart.

    This dies if N is not a positive number between 0 and 255 (inclusive).

  • text_black

  • text_blue

  • text_cyan

  • text_green

  • text_magenta

  • text_orange

  • text_red

  • text_rgb

  • text_white

  • text_yellow

    Make foreground text the named color.

  • text_bright_black

  • text_bright_blue

  • text_bright_cyan

  • text_bright_green

  • text_bright_magenta

  • text_bright_red

  • text_bright_white

  • text_bright_yellow

    Make foreground text the named color and bright (however your terminal does that).

  • text_gray

  • text_grey

    The same as text_bright_black, which most people call gray.

  • text_default

    Go back to the terminal's default text color (SGR 39). Unlike reset_all, this leaves the background color and attributes alone.

  • underline

    Turn on underlining.

Saving and restoring the cursor

Terminals have two ways to save the cursor and come back to it later: the DEC way and the SCO way. Each has only one save slot, so saving again replaces whatever you saved before; you can't nest them.

The DEC versions are the ones to use. They work in essentially every terminal, and they're what terminfo's sc and rc capabilities (tput sc) send for most terminals. The SCO versions are less predictable: some terminals save only the position, others (such as xterm and the VT510) save the same things as the DEC versions, some terminals ignore them, and in terminals with left and right margins turned on, CSI s sets the margins instead.

For the details, see the VT510 reference pages for DECSC, DECRC, SCOSC, and SCORC, and XTerm Control Sequences, which also covers the conflict between CSI s and setting the left and right margins.

The saved position is a screen position. If the screen scrolls between saving and restoring, the cursor comes back to the same row of the screen, which may now show a different line.

  • cursor_save_state

  • cursor_save_dec

  • cursor_save_all

  • decsc

    Save the cursor position, along with the current text attributes, character sets, origin mode, and a few other settings (DECSC, ESC 7). Restore it with cursor_restore_state or any of its other names.

  • cursor_restore_state

  • cursor_restore_dec

  • cursor_restore_all

  • decrc

    Put the cursor back where cursor_save_state saved it, and restore the attributes saved with it (DECRC, ESC 8).

  • cursor_save

  • cursor_save_position

    Save the cursor position the SCO way (SCOSC, CSI s). What else gets saved depends on the terminal. Prefer cursor_save_state.

  • cursor_restore

  • cursor_restore_position

    Put the cursor back where cursor_save saved it, the SCO way (SCORC, CSI u). Prefer cursor_restore_state.

  • save_cursor

    Deprecated. Use cursor_save (the same SCO sequence) or, better, cursor_save_state.

  • restore_cursor

    Deprecated. Use cursor_restore (the same SCO sequence) or, better, cursor_restore_state.

Changing the cursor shape

These use the standard DECSCUSR sequence (CSI N SP q), which works in xterm, iTerm2, kitty, Windows Terminal, the VTE terminals, tmux, and most others. iTerm2 also has its own way, iterm_set_cursor_shape, which numbers the shapes differently.

See the VT510 reference page for DECSCUSR, which defines shapes 0 through 4, and XTerm Control Sequences, which adds the bar shapes, 5 and 6.

  • cursor_shape( [ N ] )

    Set the cursor shape. N defaults to 0:

    • 0 - the terminal's default shape (usually a blinking block)

    • 1 - blinking block

    • 2 - steady block

    • 3 - blinking underline

    • 4 - steady underline

    • 5 - blinking bar

    • 6 - steady bar

    Any other value carps and returns the empty string.

  • cursor_shape_default

  • cursor_block_blinking

  • cursor_block

  • cursor_underline_blinking

  • cursor_underline

  • cursor_bar_blinking

  • cursor_bar

    Shortcuts for cursor_shape with each argument, so you don't have to remember the numbers. For example, cursor_bar is cursor_shape(6).

Character shortcuts

  • BELL - \007

  • CSI - ESC [

  • ESC - \x1b

  • OSC - ESC ]

  • ST - BELL or ESC \

  • SP - literal space

Editor-specific codes

iTerm2

iTerm2 supports proprietary

  • iterm_bg_color()

  • iterm_fg_color() OSC 4 ; -1; ? ST

    Returns an array reference of the decimal values for the Red, Green and Blue components of the background or foreground. These triplets may be 2 or 4 digits in each component.

  • iterm_start_link( URL [, ID] )

  • iterm_end_link()

    Mark some text as a clickable URL. OSC 8 ; [params] ; [url] ST id is only param

  • iterm_linked_text( TEXT, URL, [, ID] )

  • iterm_set_cursor_shape( N )

    Change the cursor shape the iTerm2 way (OSC 1337 ; CursorShape=N ST):

    • 0 Block

    • 1 Vertical bar

    • 2 Underline

    Any other N carps and returns nothing. These numbers aren't the same as the standard ones that cursor_shape uses, which work in iTerm2 and most other terminals; see "Changing the cursor shape".

  • iterm_set_block_cursor

  • iterm_set_bar_cursor

  • iterm_set_underline_cursor

    Change the cursor to a block, a vertical bar, or an underline. Like the other iTerm2 functions, these work only in iTerm2; anywhere else, they carp and return nothing.

  • set_mark

    Same as Command-Shift-M. Mark the current location and jump back to it with Command-Shift-J.

  • steal_focus

    Bring the window to the foreground.

  • clear_scrollback_history

    Erase the scrollback history.

  • post_notification

  • set_current_directory

  • change_profile

  • start_copy_to_clipboard

  • end_copy_to_clipboard

  • change_color_palette

    [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

    [value] gives the new color. The following formats are accepted:

    RGB (three hex digits, like fff) RRGGBB (six hex digits, like f0f0f0) cs:RGB (like RGB but cs gives a color space) cs:RRGGBB (like RRGGBB but cs gives a color space) If a color space is given, it should be one of:

    srgb (the standard sRGB color space) rgb (the device-specific color space) p3 (the standard P3 color space, whose gamut is supported on some newer hardware)

  • add_annotation

    OSC 1337 ; AddAnnotation=[message] ST OSC 1337 ; AddAnnotation=[length] | [message] ST OSC 1337 ; AddAnnotation=[message] | [length] | [x-coord] | [y-coord] ST OSC 1337 ; AddHiddenAnnotation=[message] ST OSC 1337 ; AddHiddenAnnotation=[length] | [message] ST OSC 1337 ; AddHiddenAnnotation=[message] | [length] | [x-coord] | [y-coord] ST `[message]`: The message to attach to the annotation. `[length]`: The number of cells to annotate. Defaults to the rest of the line beginning at the start of the annotation. `[x-coord]` and `[y-coord]`: The starting coordinate for the annotation. Defaults to the cursor's coordinate.

  • hide_cursor_guide

  • show_cursor_guide

  • iterm_attention

    Play with the dock icon.

    • fireworks - animation at the cursor

    • no - stop bouncing the dock icon

    • once - bounce the dock icon once

    • yes - bounce the dock indefinitely

  • iterm_bounce_dock_icon

    Bounce the Dock icon, continuously

  • iterm_bounce_dock_icon_once

    Bounce the Dock icon, only once

  • iterm_unbounce_dock_icon

    Stop bouncing the Dock icon

  • iterm_fireworks

    Show animated fireworks.

  • background_image_file

    OSC 1337 ; SetBackgroundImageFile=[base64] ST 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.

  • report_cell_cell

    OSC 1337 ; ReportCellSize ST The terminal responds with either:

    OSC 1337 ; ReportCellSize=[height];[width] ST Or, in newer versions:

    OSC 1337 ; ReportCellSize=[height];[width];[scale] ST [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.

    [height] and [width] are floating point values giving the size in points of a single character cell. For example:

    OSC 1337 ; ReportCellSize=17.50;8.00;2.0 ST

  • copy_to_pasteboard

    You can place a string in the system's pasteboard with this sequence:

    OSC 1337 ; Copy=:[base64] ST Where [base64] is the base64-encoded string to copy to the pasteboard.

  • report_variable

    Each iTerm2 session has internal variables (as described in Scripting Fundamentals). This escape sequence reports a variable's value:

    OSC 1337 ; ReportVariable=[base64] ST Where [base64] is a base64-encoded variable name, like session.name. It responds with:

    OSC 1337 ; ReportVariable=[base64] ST Where [base64] is a base64-encoded value.

    https://iterm2.com/documentation-scripting-fundamentals.html

  • badge

    The badge may be set with the following control sequence:

    https://iterm2.com/documentation-badges.html

    OSC 1337 ; SetBadgeFormat=Base-64 encoded badge format ST Here's an example that works in bash:

    # Set badge to show the current session name and git branch, if any is set. printf "\e]1337;SetBadgeFormat=%s\a" \ $(echo -n "\(session.name) \(user.gitBranch)" | base64)

  • downloads

    https://iterm2.com/documentation-images.html

    The width and height are given as a number followed by a unit, or the word "auto".

    iTerm2 extends the xterm protocol with a set of proprietary escape sequences. In general, the pattern is:

    ESC ] 1337 ; key = value ^G Whitespace is shown here for ease of reading: in practice, no spaces should be used.

    For file transfer and inline images, the code is:

    ESC ] 1337 ; File = [arguments] : base-64 encoded file contents ^G The arguments are formatted as key=value with a semicolon between each key-value pair. They are described below:

    Key Description of value name base-64 encoded filename. Defaults to "Unnamed file". size File size in bytes. The file transfer will be canceled if this size is exceeded. width Optional. Width to render. See notes below. height Optional. Height to render. See notes below. 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. 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. N: N character cells. Npx: N pixels. N%: N percent of the session's width or height. auto: The image's inherent size will be used to determine an appropriate dimension. More on File Transfers 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.

    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.

  • uploads

    To request the user select one or more files to upload, send:

    OSC 1337 ; RequestUpload=format=[type] ST In the future the [type] may be configurable, but for now it must always be tgz, which is a tar and gzipped file.

    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.

    If the user selects multiple files they will be placed in a directory within the tar file.

  • set_touchbar_key_levels

    You can configure touch bar key labels for function keys and for the "status" button. The code used is:

    OSC 1337 ; SetKeyLabel=[key]=[value] ST 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:

    OSC 1337 ; PushKeyLabels ST To pop them:

    OSC 1337 ; PopKeyLabels ST 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:

    OSC 1337 ; PushKeyLabels=[label] ST OSC 1337 ; PopKeyLabels=[label] ST Where [label] is an ASCII string that works best if it is unique in the stack.

  • unicode_version

    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:

    OSC 1337 ; UnicodeVersion=[n] ST Where [n] is 8 or 9

    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.

SEE ALSO

  • Everything you never wanted to know about ANSI escape codes https://notes.burke.libbey.me/ansi-escape-codes/

  • https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797

  • iTerm2 ANSI codes https://iterm2.com/documentation-escape-codes.html

SOURCE AVAILABILITY

This source is in Github:

http://github.com/briandfoy/antsy

AUTHOR

brian d foy, <briandfoy@pobox.com>

COPYRIGHT AND LICENSE

Copyright © 2021-2026, brian d foy, All Rights Reserved.

You may redistribute this under the terms of the Artistic License 2.0.