io_ansi(3)

📦
version 29.0.6 · 2 versions
, in ubuntu stonking

💖 io_ansi(3) — Erlang Module Definition 💖

bestie, this is the Erlang module definition for io_ansi, and it's literally about controlling your terminal using virtual terminal sequences. No cap. 💅

✨ NAME ✨

io_ansi — controlling the terminal using virtual terminal sequences (aka [ANSI escape codes]). 🎀

🌈 DESCRIPTION 🌈

This module provides an interface to emit and parse virtual terminal sequences (VTS), also known as [ANSI escape codes]. VTS can be used to:

  • change the style of text or background in the terminal by adding color or emphasis. 🎨
  • delete printed characters or lines. 🧹
  • move, hide or show the cursor 👀

and more things. As different terminals are interpret VTSs slightly differently, io_ansi uses the local [terminfo] database together with predefined sequences to emit the correct sequence for the terminal that is currently used. To fetch values directly from the [terminfo] database you can use tput/2, tigetnum/1 and tigetflag/1.

io_ansi provides two interfaces to emit sequences. You can either call the function representing the sequence you want to emit, for example io_ansi:blue() and it will return the sequence representing blue.

1> io_ansi:blue().
<<"\e[34m">>

This will use the [terminfo] database locally where the call is made, so it may not be correct if used across nodes.

You can also use the io_ansi:format/1,2,3 functions which works just as io_lib:bformat/3, except that it also accepts atoms and tuples that represent VTSs. For example:

1> io_ansi:format([blue,"~p"], [red]).
<<"\e[34mred\e(B\e[m">>

io_ansi:format/3 will automatically reset the terminal to its original state and strip any VTSs that are not supported by the terminal. It can also be disabled through an option. For example:

1> io_ansi:format([blue,"~p"], [red], [{enabled, false}]).
<<"red">>

Finally there is io_ansi:fwrite/1,2,3,4 which does not return the string to be printed, but instead sends it to the io:device/0 that should handle it. io_ansi:fwrite/4 works across nodes and will use the [terminfo] database where the data is outputted to decide what to emit.

Refs, bestie:

🦋 DATA TYPES 🦋

background_color()

background_color() ::
          black_background | blue_background | cyan_background |
          green_background | magenta_background | red_background |
          white_background | yellow_background | default_background |
          light_black_background | light_blue_background |
          light_cyan_background | light_green_background |
          light_magenta_background | light_red_background |
          light_white_background | light_yellow_background |
          {background, 0..255} |
          {background, R :: 0..255, G :: 0..255, B :: 0..255}.

Virtual terminal sequences that control the background color. It's giving full background glow-up energy ✨

color()

color() ::
          foreground_color() |
          background_color() |
          underline_color() |
          {modify_color,
           Index :: 0..255,
           R :: 0..255,
           G :: 0..255,
           B :: 0..255}.

Virtual terminal sequences that control color. The whole palette fantasy 💅

color_atom()

color_atom() ::
          black | blue | cyan | green | magenta | red | white | yellow |
          light_black | light_blue | light_cyan | light_green |
          light_magenta | light_red | light_white | light_yellow.

These are the named color atoms, periodt. 🌈

cursor()

cursor() ::
          {cursor,
           Line :: non_neg_integer(),
           Column :: non_neg_integer()} |
          {cursor_move,
           DeltaLine :: integer(),
           DeltaColumn :: integer()} |
          cursor_down | cursor_up | cursor_backward | cursor_forward |
          {cursor_down | cursor_backward | cursor_forward | cursor_up,
           N :: non_neg_integer()} |
          cursor_home | reverse_index | cursor_save | cursor_restore |
          cursor_show | cursor_hide | cursor_next_line |
          cursor_previous_line | cursor_horizontal_absolute |
          cursor_vertical_absolute | cursor_horizontal_vertical |
          cursor_report_position.

Virtual terminal sequences that controls the cursor. Cursor main character energy 👀

foreground_color()

foreground_color() ::
          color_atom() |
          {color, 0..255} |
          {color, R :: 0..255, G :: 0..255, B :: 0..255} |
          default_color.

Virtual terminal sequences that control the foreground (aka text) color. Text color, bestie, the moment 💖

format()

format() :: [string() | vts()].

The format string that can be passed to format/3 and fwrite/4. 💅

hyperlink() ::
          {hyperlink,
           URL :: uri_string:uri_string(),
           Text :: unicode:chardata()} |
          {hyperlink,
           URL :: uri_string:uri_string(),
           hyperlink_params(),
           Text :: unicode:chardata()} |
          {hyperlink_start, URL :: uri_string:uri_string()} |
          {hyperlink_start,
           URL :: uri_string:uri_string(),
           hyperlink_params()} |
          hyperlink_reset.

Virtual terminal sequences that control whether emitted text shall be a hyper link or not. Serving link realness 🔗

hyperlink_params() ::
          [{Key :: unicode:chardata(), Value :: unicode:chardata()}].

A list of key/value chardata pairs for the hyperlink fantasy. 🎀

input()

input() ::
          keypad_transmit_mode | keypad_transmit_mode_off |
          kcursor_down | kcursor_up | kcursor_backward |
          kcursor_forward | kcursor_home | kcursor_end.

Virtual terminal sequences for cursor input. Input mode, but make it cursor-coded ⌨️

option()

option() ::
          {reset, boolean()} |
          {enabled, boolean()} |
          {color, boolean()} |
          io_lib:format_options().

One option in the options list, bestie. ✨

options()

options() :: [option()].

A list of option()s. Options, options, options 💅

style()

style() ::
          bold | bold_off | blink | blink_off | dim | dim_off |
          invisible | invisible_off | italic | italic_off | inverse |
          inverse_off | overline | overline_off | strikethrough |
          strikethrough_off |
          underline_style().

Virtual terminal sequences that control text style. Style check: passed 💅

tab()

tab() :: tab | tab_backward | tab_set | tab_clear | tab_clear_all.

Virtual terminal sequences that works with tabs. Tab tab tab, organize bestie ✨

text()

text() ::
          text_formatting() |
          text_modification() |
          alternate_character_set_mode |
          alternate_character_set_mode_off.

Virtual terminal sequences that works on text. Text is the moment. 💖

text_formatting()

text_formatting() :: color() | style() | hyperlink().

Virtual terminal sequences that control text formatting. Glow-up combo 💅

text_modification()

text_modification() ::
          clear | erase_display | insert_character | delete_character |
          erase_character | insert_line | delete_line | erase_line.

Virtual terminal sequences that can erase or overwrite text. Deleting is self-care 🧹

underline_color()

underline_color() ::
          black_underline | blue_underline | cyan_underline |
          green_underline | magenta_underline | red_underline |
          white_underline | yellow_underline | default_underline |
          light_black_underline | light_blue_underline |
          light_cyan_underline | light_green_underline |
          light_magenta_underline | light_red_underline |
          light_white_underline | light_yellow_underline |
          {underline_color, 0..255} |
          {underline_color, R :: 0..255, G :: 0..255, B :: 0..255}.

Virtual terminal sequences that control underline color. Underline but make it colorful 🌈

underline_style()

underline_style() ::
          underline | underline_off | double_underline |
          curly_underline | dotted_underline | dashed_underline.

Virtual terminal sequences that control underline style. Underline aesthetics 💅

vts()

vts() ::
          text() |
          cursor() |
          window() |
          tab() |
          input() |
          reset | device_report_attributes.

Virtual terminal sequences. The whole VTS universe 🪐

window()

window() ::
          alternate_screen | alternate_screen_off | scroll_forward |
          scroll_backward | scroll_change_region.

Virtual terminal sequences that controls the screen. Window seat, bestie 🪟

🚀 FUNCTIONS 🚀

alternate_character_set_mode()

alternate_character_set_mode() -> unicode:chardata().

Enable the alternate characters set mode. Bestie, it's giving alternate character set realness. ✨

Example:

1> io_ansi:alternate_character_set_mode().
<<"\e(0">>
2> io_ansi:fwrite(["%%", alternate_character_set_mode, " tqqu\n", alternate_character_set_mode_off]).
%% ├──┤
ok

alternate_character_set_mode_off()

alternate_character_set_mode_off() -> unicode:chardata().

Disable the alternate characters set mode. Bye alternate characters. 👋

Example:

1> io_ansi:alternate_character_set_mode_off().
<<"\e(B">>

alternate_screen()

alternate_screen() -> unicode:chardata().

Activate the alternate screen buffer.

The alternate screen buffer is a separate screen buffer that full-screen terminal applications (like vim, less, htop, or man) use to display their content. When activated, the current screen content and cursor position are saved. When deactivated with alternate_screen_off/0, the original screen content is restored, making it appear as if the full-screen application was never there.

Example:

1> io_ansi:alternate_screen().
<<"\e[?1049h\e[22;0;0t">>

alternate_screen_off()

alternate_screen_off() -> unicode:chardata().

Deactivate the alternate screen. Return to your regularly scheduled terminal. 🦋

Example:

1> io_ansi:alternate_screen_off().
<<"\e[?1049l\e[23;0;0t">>

background(Index :: 0..255 | 0..87 | color_atom())

background(Index :: 0..255 | 0..87 | color_atom()) ->
                    unicode:chardata().

Change background color to index color. Index 0-15 are equivilant to the named colors in background_color/0 in the order that they are listed.

Example:

1> io_ansi:background(2).
<<"\e[42m">>
2> io_ansi:background(80).
<<"\e[48;5;80m">>

background(0..255, 0..255, 0..255)

background(0..255, 0..255, 0..255) -> unicode:chardata().

Change background color to RGB color. RGB background? Periodt. 🌈

Example:

1> io_ansi:background(255, 255, 0).
<<"\e[48;2;255;255;0m">>

black()

black() -> unicode:chardata().

Change foreground (aka text) color to black. Black text, classic, no cap. 🖤

Example:

1> io_ansi:black().
<<"\e[30m">>

black_background()

black_background() -> unicode:chardata().

Change background color to black. Black background, mysterious era. 🖤

Example:

1> io_ansi:black_background().
<<"\e[40m">>

black_underline()

black_underline() -> unicode:chardata().

Change underline color to black. Heads up: not widely supported. 😭

Example:

1> io_ansi:black_underline().
<<"\e[58;5;0m">>
blink() -> unicode:chardata().

Turn on blink text style. Heads up: not widely supported. Blink blink, but maybe not on every terminal. 💀

Example:

1> io_ansi:blink().
<<"\e[5m">>

ok so this one turns the blink text style off 💖

Example:

1> io_ansi:blink_off().
<<"\e[25m">>

blue() -> unicode:chardata()

changes the foreground (aka the text) color to blue 💙 ngl this is everyone's favorite

Example:

1> io_ansi:blue().
<<"\e[34m">>

blue_background() -> unicode:chardata()

same energy but now it's the background that goes blue 💙

Example:

1> io_ansi:blue_background().
<<"\e[44m">>

blue_underline() -> unicode:chardata()

sets the underline color to blue. bestie, heads up: not widely supported 💀 so don't be surprised if some terminals just ignore you

Example:

1> io_ansi:blue_underline().
<<"\e[58;5;4m">>

bold() -> unicode:chardata()

turns bold text style on 🔥 main character energy, fr

Example:

1> io_ansi:bold().
<<"\e[1m">>

bold_off() -> unicode:chardata()

and this one turns bold off 🙈

Example:

1> io_ansi:bold_off().
<<"\e[22m">>

clear() -> unicode:chardata()

wipes the whole screen AND sends the cursor home 🧹✨ clean slate, we love to see it

Example:

1> io_ansi:clear().
<<"\e[H\e[2J">>

color(Index :: 0..255 | 0..87 | color_atom()) -> unicode:chardata()

sets the foreground (aka text) color to an index color 🌈 heads up: Index 0-15 are equivalent to the named colors in foreground_color/0, in the order that they're listed there. iykyk

Example:

1> io_ansi:color(5).
<<"\e[35m">>
2> io_ansi:color(80).
<<"\e[38;5;80m">>

color(0..255, 0..255, 0..255) -> unicode:chardata()

gives you foreground (aka text) color as an RGB color 🎨 three numbers, full customization, we're obsessed

Example:

1> io_ansi:color(255, 0, 0).
<<"\e[38;2;255;0;0m">>

color_name_to_index(Color :: color_atom()) -> 0..15

takes a color atom and hands you back its index, 0-15 💅 super handy utility behavior

Example:

1> io_ansi:color_name_to_index(red).
1

curly_underline() -> unicode:chardata()

turns on the curly underline text style 🌀 not widely supported so vibe check your terminal first

Example:

1> io_ansi:curly_underline().
<<"\e[4:3m">>

cursor(Line :: integer(), Column :: integer()) -> unicode:chardata()

moves the cursor to the position you give it 🎯 and listen: position 0,0 is at the top left of the terminal

Example:

1> io_ansi:cursor(5, 10).
<<"\e[6;11H">>

cursor_backward() -> unicode:chardata()

moves the cursor backward N characters ⬅️

Example:

1> io_ansi:cursor_backward().
<<"\b">>

cursor_backward(N :: integer()) -> unicode:chardata()

same thing, moves the cursor backward N characters ⬅️⬅️

Example:

1> io_ansi:cursor_backward(42).
<<"\e[42D">>

cursor_down() -> unicode:chardata()

moves the cursor down one line ⬇️

Example:

1> io_ansi:cursor_down().
<<"\n">>

cursor_down(N :: integer()) -> unicode:chardata()

moves the cursor down N lines ⬇️⬇️

Example:

1> io_ansi:cursor_down(42).
<<"\e[42B">>

cursor_forward() -> unicode:chardata()

moves the cursor forward one character ➡️

Example:

1> io_ansi:cursor_forward().
<<"\e[C">>

cursor_forward(N :: integer()) -> unicode:chardata()

moves the cursor forward N characters ➡️➡️

Example:

1> io_ansi:cursor_forward().
<<"\e[C">>

cursor_get_position() -> {Row :: non_neg_integer(), Column :: non_neg_integer()} | {error, string()}

grabs the current cursor position and gives it to you as {Row, Column} 📍 either that tuple or {error, string()}, no in between

Example:

## Enter noshell-raw mode and request cursor location and then print
## the reply to stdout.
$ erl -noshell -eval 'shell:start_interactive({noshell,raw}),
    {Row,Col} = io_ansi:cursor_get_position(),
    io:format("~p",[{Row,Col}])' -s init stop
{58,1}

cursor_hide() -> unicode:chardata()

makes the cursor disappear 🙈 poof

Example:

1> io_ansi:cursor_hide().
<<"\e[?25l">>

cursor_home() -> unicode:chardata()

sends the cursor back to the start of the current line 🏠

Example:

1> io_ansi:cursor_home().
<<"\e[H">>

cursor_horizontal_absolute(X :: integer()) -> unicode:chardata()

moves the cursor to column X ↔️

Example:

1> io_ansi:cursor_horizontal_absolute(10).
<<"\e[11G">>

cursor_horizontal_vertical(X :: integer(), Y :: integer()) -> unicode:chardata()

moves the cursor to line X and column Y 🎯 and note that position 1,1 is at the top left of the terminal, periodt

Example:

1> io_ansi:cursor_horizontal_vertical(10, 20).
<<"\e[10;20f">>

cursor_move(DeltaLine :: integer(), DeltaColumn :: integer()) -> unicode:chardata()

moves the cursor relative to wherever it already is 🕺 so: positive DeltaLine moves down, negative moves up. Positive DeltaColumn moves right (forward), negative moves left (backward).

Example:

1> io_ansi:cursor_move(-5, 0).
<<"\e[5A">>
2> io_ansi:cursor_move(0, 10).
<<"\e[10C">>
3> io_ansi:cursor_move(3, -2).
<<"\e[3B\e[2D">>
4> io_ansi:cursor_move(0, 0).
<<>>

cursor_next_line() -> unicode:chardata()

moves the cursor down one line and then returns it to home 🏠⬇️

Example:

> io_ansi:cursor_next_line().
<<"\e[E">>

cursor_previous_line() -> unicode:chardata()

moves the cursor up one line and then returns it to home 🏠⬆️

Example:

1> io_ansi:cursor_previous_line().
<<"\e[F">>

cursor_report_position() -> unicode:chardata()

tells the terminal to report the current cursor position 📢 it's giving "hey terminal, where u at"

Examples:

1> io_ansi:cursor_report_position().
~"\e[6n"

## Enter noshell-raw mode and request cursor location and then print
## the reply to stdout.
$ erl -noshell -eval 'shell:start_interactive({noshell,raw}),
    io_ansi:fwrite([cursor_report_position]),
    io:format("~p",[io:get_chars("",20)])' -s init stop
"\e[58;1R"

the reported cursor position in that example is row 58 and column 1, and both of them are 1 index based 👑

cursor_restore() -> unicode:chardata()

restores a saved cursor position 💾 as in, the one you saved earlier

Example:

1> io_ansi:cursor_restore().
<<"\e8">>

cursor_save() -> unicode:chardata()

saves the current cursor position 💾 bookmark behavior, we stan

Example:

1> io_ansi:cursor_save().
<<"\e7">>

cursor_show() -> unicode:chardata()

shows the cursor 👀 (the reverse of hiding it, obvi)

Example:

1> io_ansi:cursor_show().
<<"\e[?12;25h">>

cursor_up() -> unicode:chardata()

moves the cursor up one line ⬆️

Example:

1> io_ansi:cursor_up().
<<"\e[A">>

cursor_up(N :: integer()) -> unicode:chardata()

moves the cursor up N lines ⬆️⬆️

Example:

1> io_ansi:cursor_up(42).
<<"\e[42A">>

cursor_vertical_absolute(X :: integer()) -> unicode:chardata()

moves the cursor to line X ↕️

Example:

1> io_ansi:cursor_vertical_absolute(20).
<<"\e[21d">>

cyan() -> unicode:chardata()

sets the foreground (aka text) color to cyan 🩵

Example:

1> io_ansi:cyan().
<<"\e[36m">>

cyan_background() -> unicode:chardata()

sets the background color to cyan 🩵

Example:

1> io_ansi:cyan_background().
<<"\e[46m">>

cyan_underline() -> unicode:chardata()

sets the underline color to cyan 🩵 not widely supported, so it may just not show up for you 💀

Example:

1> io_ansi:cyan_underline().
<<"\e[58;5;6m">>

dashed_underline() -> unicode:chardata()

turns on the dashed underline text style ✨ not widely supported — dramatic little styling, tbh

Example:

1> io_ansi:dashed_underline().
<<"\e[4:5m">>

default_background() -> unicode:chardata()

sets the background color back to the default color 🔄 reset era

Example:

1> io_ansi:default_background().
<<"\e[49m">>

default_color() -> unicode:chardata()

sets the foreground (aka text) color back to the default color 🔄

Example:

1> io_ansi:default_color().
<<"\e[39m">>

default_underline_color() -> unicode:chardata()

resets the underline color to the default 🔄

Example:

1> io_ansi:default_underline_color().
<<"\e[59m">>

delete_character() -> unicode:chardata()

deletes 1 character at the cursor ✂️ gone, not sorry

Example:

1> io_ansi:delete_character().
<<"\e[P">>

delete_character(Chars :: integer()) -> unicode:chardata()

deletes Chars characters at the cursor by shifting the text Chars characters to the left ✂️⬅️

Example:

1> io_ansi:delete_character(2).
<<"\e[2P">>

delete_line() -> unicode:chardata()

deletes 1 line at the cursor ✂️📄

Example:

1> io_ansi:delete_line().
<<"\e[M">>

delete_line(Lines :: integer()) -> unicode:chardata()

deletes Lines lines at the cursor ✂️📄📄

Example:

1> io_ansi:delete_line(3).
<<"\e[3M">>

device_report_attributes() -> unicode:chardata()

tells the terminal emulator to report its device attributes 📋 like, terminal, introduce yourself bestie

Examples:

1> io_ansi:device_report_attributes().
<<"\e[0c">>
  • -a — like, show everything, no secrets ✨

🎀 Enter noshell-raw mode and request device attributes and then print

## the reply to stdout.
$ erl -noshell -eval 'shell:start_interactive({noshell,raw}),
     io_ansi:fwrite([device_report_attributes]),
     io:format("~p",[io:get_chars("",20)])' -s init stop
"\e[?65;1;9c"

💅 Functionz, bestie (the saga continues)

dim() -> unicode:chardata().

okay so this one turns on dim text style 💫 no cap, it's not widely supported tho, so don't come crying to me if ur terminal is like "huh? 🧍"

Example:

1> io_ansi:dim().
<<"\e[2m">>

dim_off() -> unicode:chardata().

and this one turns it OFF, we're un-dimming, we're normalizing, we're healing 🌸

Example:

1> io_ansi:dim_off().
<<"\e[22m">>

dotted_underline() -> unicode:chardata().

dotted underline!! very cute, very demure 🎀 but not widely supported fr fr, so vibe check ur terminal first

Example:

1> io_ansi:dotted_underline().
<<"\e[4:4m">>

double_underline() -> unicode:chardata().

DOUBLE underline?? iconic. main character energy 💅 lowkey not widely supported too, just so you know

Example:

1> io_ansi:double_underline().
<<"\e[4:2m">>

enabled() -> boolean().

this is the vibe check bestie — it asks: can io:user/0 even interpret ANSI escape sequences? 👑

Example:

1> io_ansi:enabled().
true

enabled(io:device()) -> boolean().

same vibe check but for a specific Device 🦋 asking "can you interpret ANSI escape sequences?"

so like, how does it know? It checks if Device is a terminal AND if the TERM environment variable is set to a terminal type that supports virtual terminal sequences. the way that it just knows 💅

Example:

1> io_ansi:enabled(standard_error).
true
2> {ok, File} = file:open("tmp",[write]), io_ansi:enabled(File).
false

erase_character(Chars :: integer()) -> unicode:chardata().

erases Chars characters at the cursor by making Chars characters before the cursor blank ✨ poof, gone, not me erasing my mistakes 🫶

Example:

1> io_ansi:erase_character(4).
<<"\e[4X">>

erase_display() -> unicode:chardata().

clears the screen after the cursor 🌈 fresh start energy

Example:

1> io_ansi:erase_display().
<<"\e[J">>

erase_line() -> unicode:chardata().

erases the line at the cursor, periodt 💅

Example:

1> io_ansi:erase_line().
<<"\e[K">>

format(format(), Data :: [term()], options()) -> unicode:unicode_binary().

returns a character list that represents Data formatted in accordance with Format 🎀

okay so this works just like io_lib:bformat/2, where Data is a list of strings as well as atoms and tuples representing virtual terminal sequences as part of the Format string 🔥

here's the tea tho: calling format/3 will always emit a reset/0 VTS at the end of the returned string. don't want that? set the reset option to false 🙈

wanna force enable or disable emitting VTSs? set the enabled option to true or false. by default the emitting of VTSs is enabled if enabled/0 returns true and disabled otherwise 💫

wanna disable emitting of color VTSs but still emit other VTSs? set the color option to false. the default color option is true unless the NO_COLOR environment variable is set to a non-empty value, in which case the default is false 👑

Example:

1> io_ansi:format([blue, underline, "Hello world"]).
~"\e[34m\e[4mHello world\e(B\e[m"
2> io_ansi:format([blue, underline, "Hello ~p"],[world]).
~"\e[34m\e[4mHello world\e(B\e[m"
3> io_ansi:format([blue, underline, "Hello ~p"],[world],[{reset,false}]).
~"\e[34m\e[4mHello world"
4> io_ansi:format([blue, underline, "Hello ~p"],[world],[{enabled,false}]).
~"Hello world"
5> io_ansi:format([blue, underline, "Hello ~p"],[world],[{color,false}]).
~"\e[4mHello world\e(B\e[m"

for a detailed description of the available formatting options, see io:fwrite/3 🦋

fwrite(IODevice :: io:device(), Format :: format(), [term()], options()) -> ok.

writes the items in Data on the IoDevice in accordance with Format ✨

this works just as io:fwrite/2, except that it also allows atoms and tuples representing virtual terminal sequences (VTS) as part of the Format string 🎀

see format/3 for the details on how the different Options can be used 💅

Example:

1> io_ansi:fwrite([blue, "%% Hello world\n"]).
%% Hello world
ok
2> io_ansi:fwrite([underline, "%% Hello ~p\n"], [world]).
%% Hello world
ok
3> io_ansi:fwrite([invalid_code, "%% Hello ~p\n"], [world]).
** exception error: {error,{put_ansi,unicode,invalid_code}}

the decision about what each VTS should be converted to is done by the destination I/O device 🧚 meaning: if the I/O device is on a remote node, the terminfo database loaded into that remote node will be used. so it's giving ✨remote delegation✨

all VTSs are stripped if the target I/O device does not support handling VTSs, either because:

  • it is not implemented by the device (for example if the device is a file:io_server/0), or
  • the device does not support a certain VTS 😭

wanna force usage of VTSs? you can pass {enabled, true} and that will use the local defintions to translate 👑

green() -> unicode:chardata().

changes foreground (aka text) color to green 🌈 and green is the color, periodt

Example:

1> io_ansi:green().
<<"\e[32m">>

green_background() -> unicode:chardata().

changes the background color to green 🍓 we love a green moment

Example:

1> io_ansi:green_background().
<<"\e[42m">>

green_underline() -> unicode:chardata().

changes underline color to green ✨ not widely supported bestie, so don't be surprised if ur terminal ghosts u 💀

Example:

1> io_ansi:green_underline().
<<"\e[58;5;2m">>

stops emitting a hyperlink 🫶 closing that chapter, moving on

Example:

1> io_ansi:hyperlink_reset().
<<"\e]8;;\e\\">>

starts a hyperlink pointing to the given URL using Params 🔗✨

the hyperlink can be any type of URL, but typically it would be a file or http URL 💅

Example:

1> io_ansi:hyperlink_start("https://erlang.org").
<<"\e]8;https://erlang.org;\e\\">>
2> io_ansi:format([{hyperlink_start, "file://tmp/debug.log"},"debug log",hyperlink_reset]).
~"\e]8;file://tmp/debug.log;\e\\debug log\e]8;;\e\\\e(B\e[m"

see Hyperlinks (a.k.a. HTML-like anchors) in terminal emulators for more details on limitations and usage of terminal hyperlinks 🎀

insert_character(Chars :: integer()) -> unicode:chardata().

inserts Chars at cursor 🌸 not me inserting myself into the conversation

Example:

1> io_ansi:insert_character(3).
<<"\e[3@">>

insert_line() -> unicode:chardata().

inserts 1 line at cursor ✨ a whole single line, a moment

Example:

1> io_ansi:insert_line().
<<"\e[L">>

insert_line(Lines :: integer()) -> unicode:chardata().

inserts Lines lines at cursor 🔥 okay now we're inserting MULTIPLE lines, we're expansive

Example:

1> io_ansi:insert_line(2).
<<"\e[2L">>

inverse() -> unicode:chardata().

turns on inverse text style 👑 inverse is also called reverse video or standout mode 💅 iykyk

Example:

1> io_ansi:inverse().
<<"\e[7m">>

inverse_off() -> unicode:chardata().

turns off inverse text style 🦋 (inverse is also called reverse video or standout mode, just so you know bestie)

Example:

1> io_ansi:inverse_off().
<<"\e[27m">>

invisible() -> unicode:chardata().

turns on invisible text style 👻 not widely supported so it's giving "i'm not here" energy fr fr

Example:

1> io_ansi:invisible().
<<"\e[8m">>

invisible_off() -> unicode:chardata().

turns off invisible text style ✨ back to being seen, we love visibility

Example:

1> io_ansi:invisible_off().
<<"\e[28m">>

italic() -> unicode:chardata().

turns on italic text style 💫 not widely supported tho, sad but true 😭

Example:

1> io_ansi:italic().
<<"\e[3m">>

italic_off() -> unicode:chardata().

turns off italic text style 🌸 un-italicizing, un-slanting, unbothered

Example:

1> io_ansi:italic_off().
<<"\e[23m">>

keypad_transmit_mode() -> unicode:chardata().

enables keypad transmit mode 🎮 very niche, very specific, very slay

Example:

1> io_ansi:keypad_transmit_mode().
<<"\e[?1h\e=">>

keypad_transmit_mode_off() -> unicode:chardata().

disables keypad transmit mode 🙈 turning it off, closing the door, moving on

Example:

1> io_ansi:keypad_transmit_mode_off().
<<"\e[?1l\e>">>

light_black() -> unicode:chardata().

changes foreground (aka text) color to light black 🖤 which is honestly just... grey? but we don't question the naming here

Example:

1> io_ansi:light_black().
<<"\e[90m">>

light_black_background() -> unicode:chardata().

changes background color to light black 🦋 again, we're just vibing with the names

Example:

1> io_ansi:light_black_background().
<<"\e[100m">>

light_black_underline() -> unicode:chardata().

changes underline color to light black ✨ not widely supported so ur terminal might just be like "???" 💀

Example:

1> io_ansi:light_black_underline().
<<"\e[58;5;8m">>

light_blue() -> unicode:chardata().

changes foreground (aka text) color to light blue 💙 a soft, gentle, dreamy moment

Example:

1> io_ansi:light_blue().
<<"\e[94m">>

light_blue_background() -> unicode:chardata().

changes background color to light blue 🌈 like a lil sky moment, so cute

Example:

1> io_ansi:light_blue_background().
<<"\e[104m">>

light_blue_underline() -> unicode:chardata().

changes underline color to light blue 🎀 not widely supported bestie, so temper ur expectations

Example:

1> io_ansi:light_blue_underline().
<<"\e[58;5;12m">>

light_cyan() -> unicode:chardata().

changes foreground (aka text) color to light cyan 🦋 so fresh, so clean, so iconic

Example:

1> io_ansi:light_cyan().
<<"\e[96m">>
1> io_ansi:light_cyan().
<<"\e[96m">>

🩵 light_cyan_background()

light_cyan_background() -> unicode:chardata().

paints the background light cyan instead of the letters themselves. it's giving pool water aesthetic 🌊

Example:

1> io_ansi:light_cyan_background().
<<"\e[106m">>

🩵 light_cyan_underline()

light_cyan_underline() -> unicode:chardata().

changes your underline color to light cyan 💅 heads up bestie, this one is Not widely supported.

Example:

1> io_ansi:light_cyan_underline().
<<"\e[58;5;14m">>

🍀 light_green()

light_green() -> unicode:chardata().

foreground (aka your text, the actual letters) goes light green 🌱

Example:

1> io_ansi:light_green().
<<"\e[92m">>

🍀 light_green_background()

light_green_background() -> unicode:chardata().

background color → light green. freshly mowed lawn energy, no cap 🌈

Example:

1> io_ansi:light_green_background().
<<"\e[102m">>

🍀 light_green_underline()

light_green_underline() -> unicode:chardata().

underline color → light green. Not widely supported, so vibe check your terminal first fr fr.

Example:

1> io_ansi:light_green_underline().
<<"\e[58;5;10m">>

💜 light_magenta()

light_magenta() -> unicode:chardata().

foreground (aka text) color → light magenta ✨

Example:

1> io_ansi:light_magenta().
<<"\e[95m">>

💜 light_magenta_background()

light_magenta_background() -> unicode:chardata().

slaps light magenta onto the background 🎀

Example:

1> io_ansi:light_magenta_background().
<<"\e[105m">>

💜 light_magenta_underline()

light_magenta_underline() -> unicode:chardata().

underline color → light magenta. Not widely supported 😭

Example:

1> io_ansi:light_magenta_underline().
<<"\e[58;5;13m">>

🍓 light_red()

light_red() -> unicode:chardata().

foreground (aka text) color → light red 🍓

Example:

1> io_ansi:light_red().
<<"\e[91m">>

🍓 light_red_background()

light_red_background() -> unicode:chardata().

background color → light red 🔥

Example:

1> io_ansi:light_red_background().
<<"\e[101m">>

🍓 light_red_underline()

light_red_underline() -> unicode:chardata().

underline color → light red. Not widely supported, iykyk.

Example:

1> io_ansi:light_red_underline().
<<"\e[58;5;9m">>

🤍 light_white()

light_white() -> unicode:chardata().

foreground (aka text) color → light white. bright bright, main character glow ⭐

Example:

1> io_ansi:light_white().
<<"\e[97m">>

🤍 light_white_background()

light_white_background() -> unicode:chardata().

background color → light white. blinding in the best way 💀

Example:

1> io_ansi:light_white_background().
<<"\e[107m">>

🤍 light_white_underline()

light_white_underline() -> unicode:chardata().

underline color → light white. Not widely supported ngl.

Example:

1> io_ansi:light_white_underline().
<<"\e[58;5;15m">>

🌟 light_yellow()

light_yellow() -> unicode:chardata().

foreground (aka text) color → light yellow ✨ sunshine coded.

Example:

1> io_ansi:light_yellow().
<<"\e[93m">>

🌟 light_yellow_background()

light_yellow_background() -> unicode:chardata().

background color → light yellow ⭐

Example:

1> io_ansi:light_yellow_background().
<<"\e[103m">>

🌟 light_yellow_underline()

light_yellow_underline() -> unicode:chardata().

underline color → light yellow. Not widely supported 🙈

Example:

1> io_ansi:light_yellow_underline().
<<"\e[58;5;11m">>

💅 magenta()

magenta() -> unicode:chardata().

foreground (aka text) color → magenta, the regular-strength one, not the light one 💜

Example:

1> io_ansi:magenta().
<<"\e[35m">>

💅 magenta_background()

magenta_background() -> unicode:chardata().

background color → magenta 🎀

Example:

1> io_ansi:magenta_background().
<<"\e[45m">>

💅 magenta_underline()

magenta_underline() -> unicode:chardata().

underline color → magenta. Not widely supported 😭

Example:

1> io_ansi:magenta_underline().
<<"\e[58;5;5m">>

🎨 modify_color()

modify_color(Index :: 0..255,
             R :: 0..255,
             G :: 0..255,
             B :: 0..255) ->
                unicode:chardata().

okay this is the glow-up function bestie, it lets you redefine a palette slot. it modifies the color referenced by Index to be the RGB you pass in, with Index, R, G and B all living in the range 0..255 🖌️

real talk: calling this for Index 0-15 will change the color of the named colors in foreground_color/0 and background_color/0. so yes, you can literally rewrite what "red" means 👑

Example:

1> io_ansi:modify_color(1, 255, 100, 0).
<<"\e]4;1;rgb:41/19/00\e\\">>

➖ overline()

overline() -> unicode:chardata().

turns on the overline text style — a little line chillin' above your letters ✨

Example:

1> io_ansi:overline().
<<"\e[53m">>

➖ overline_off()

overline_off() -> unicode:chardata().

turns off the overline text style. the line has left the chat 👋

Example:

1> io_ansi:overline_off().
<<"\e[55m">>

❤️ red()

red() -> unicode:chardata().

foreground (aka text) color → red ❤️

Example:

1> io_ansi:red().
<<"\e[31m">>

❤️ red_background()

red_background() -> unicode:chardata().

background color → red 🔥

Example:

1> io_ansi:red_background().
<<"\e[41m">>

❤️ red_underline()

red_underline() -> unicode:chardata().

underline color → red. Not widely supported 🙈

Example:

1> io_ansi:red_underline().
<<"\e[58;5;1m">>

✨ render()

render([vts() | unicode:chardata()], options()) ->
                unicode:chardata().

renders terminal sequences in Data, and this is the one you'll be calling constantly, lowkey the backbone of the whole module 🫶

Data may contain either virtual terminal sequences, which are rendered, or unicode:chardata(), which are left as is.

it accepts the same options as format/3 ✨

Example:

1> io_ansi:render([blue, underline, "Hello world"]).
[~"\e[34m",~"\e[4m","Hello world",~"\e(B\e[m"]
2> io_ansi:render([blue, underline, ~"Hello world"],[{reset,false}]).
[~"\e[34m",~"\e[4m",~"Hello world"]
3> io_ansi:render([blue, underline, ~"Hello world"],[{enabled,false}]).
[~"Hello world"]
4> io_ansi:render([blue, underline, "Hello ", $\n, ~"world"],[{color,false}]).
[~"\e[4m","Hello ", $\n, ~"world",~"\e(B\e[m"]
5> io_ansi:render([invalid_code, "Hello world"]).
** exception error: {invalid_code,invalid_code}
     in function  io_ansi:render_internal/5

🔄 reset()

reset() -> unicode:chardata().

resets virtual terminal sequences to their original state 🌈

important caveat bestie: this only resets the things supported by the loaded terminfo database, which means that OSCs such as hyperlink_start/2 are not reset — you have to reset those yourself by emitting hyperlink_reset/0. don't get got 💀

Example:

1> io_ansi:reset().
<<"\e(B\e[m">>

⬆️ reverse_index()

reverse_index() -> unicode:chardata().

moves the cursor up one line, but keeps the cursor on the same location on the screen by scrolling the screen down 🌀 yes that's the whole trick, no cap.

Example:

1> io_ansi:reverse_index().
<<"\eM">>

🔍 scan()

scan(unicode:chardata()) ->
                [unicode:unicode_binary() |
                 vts() |
                 {csi, unicode:unicode_binary()}].

scans the string for virtual terminal sequences 👀 the recognized VTSs get converted into the corresponding vts/0.

if you intend to parse arrow keys, it is recommended that you first set the terminal in application mode by using keypad_transmit_mode/0 — that makes it way easier for io_ansi to correctly detect arrow keys 🎯

any unrecognized control sequence introducers get placed in a tuple tagged with csi.

Example:

1> io_ansi:scan("\eOA").
[kcursor_up]
2> io_ansi:scan("\eOB").
[kcursor_down]
3> io_ansi:scan(io_ansi:format([bold, "text"])).
[bold, ~"text", reset]
4> io_ansi:scan(io_ansi:format([{cursor, 0, 0}])).
[{csi, ~"\e[1;1H"}, reset]

⬅️ scroll_backward()

scroll_backward() -> unicode:chardata().

scrolls the screen backward 1 step 🌀

Example:

1> io_ansi:scroll_backward().
<<"\e[1T">>

⬅️ scroll_backward/1

scroll_backward(Steps :: integer()) -> unicode:chardata().

scrolls the screen backward N step, where N is Steps 💫

Example:

1> io_ansi:scroll_backward(42).
<<"\e[42T">>

📐 scroll_change_region()

scroll_change_region(Line1 :: integer(), Line2 :: integer()) ->
                                unicode:chardata().

changes the scrolling region to be from Line1 to Line2 📏

Example:

1> io_ansi:scroll_change_region(10, 20).
<<"\e[11;21r">>

➡️ scroll_forward()

scroll_forward() -> unicode:chardata().

scrolls the screen forward 1 step 🌊

Example:

1> io_ansi:scroll_forward().
<<"\e[1S">>

➡️ scroll_forward/1

scroll_forward(N :: integer()) -> unicode:chardata().

scrolls the screen forward N step, N being the arg you hand it ✨

Example:

1> io_ansi:scroll_forward(42).
<<"\e[42S">>

🚫 strikethrough()

strikethrough() -> unicode:chardata().

turns on the strikethrough text style. Not widely supported, so temper your expectations bestie 🥲

Example:

1> io_ansi:strikethrough().
<<"\e[9m">>

🚫 strikethrough_off()

strikethrough_off() -> unicode:chardata().

turns off the strikethrough text style. back to smooth letters 💅

Example:

1> io_ansi:strikethrough_off().
<<"\e[29m">>

➡️ tab()

tab() -> unicode:chardata().

moves the cursor one tab forward 🎀

Example:

1> io_ansi:tab().
<<"\t">>

⬅️ tab_backward()

tab_backward() -> unicode:chardata().

moves the cursor one tab backward 🦋

Example:

1> io_ansi:tab_backward().
<<"\e[Z">>

🧹 tab_clear()

tab_clear() -> unicode:chardata().

clears any tab location sitting at the current cursor location 🧽

Example:

1> io_ansi:tab_clear().
<<"\e[0g">>

🧹 tab_clear_all()

tab_clear_all() -> unicode:chardata().

clears all tab locations. scorched earth, no survivors 🔥

Example:

1> io_ansi:tab_clear_all().
<<"\e[3g">>

📌 tab_set()

tab_set() -> unicode:chardata().

sets a new tab location at the current cursor location 📍

Example:

1> io_ansi:tab_set().
<<"\eH">>

🎀 tigetflag/1 — terminfo flag check, bestie 🎀

tigetflag(TermInfoCapName :: string()) -> boolean().

Okay so this one returns true if the terminfo capability is available, otherwise it hands you false. That's the whole vibe. The names of the terminal capabilities can be found in the terminfo documentation, or by calling tinfo/0 and letting it spill the tea. tigetflag/1 will use the terminfo definition associated with the TERM environment variable when the Erlang VM is started. It is not possible to change after startup, so set it before, bestie. ✨

Example:

1> io_ansi:tigetflag("xn").
true
2> io_ansi:tigetflag("foobar").
false

💅 tigetnum/1 — numeric terminfo cap vibes 💅

tigetnum(TermInfoCapName :: string()) -> -1 | non_neg_integer().

Returns the number representing a terminfo capability. The names of the terminal capabilities can be found in the terminfo documentation, or by calling tinfo/0. tigetnum/1 will use the terminfo definition associated with the TERM environment variable when the Erlang VM is started. It is not possible to change after startup. Returns -1 if the capability is not available. No cap, fr fr. 🫶

Example:

1> io_ansi:tigetnum("co").
80
2> io_ansi:tigetnum("foobar").
-1

🦋 tinfo/0 — the whole terminfo guest list 🦋

tinfo() ->
              #{bool :=
                    [#{code := string(),
                       name := string(),
                       full_name := string()}]}.

Returns information about all available terminfo capabilities. See the terminfo documentation for details on each. tinfo/0 will use the terminfo definition associated with the TERM environment variable when the Erlang VM is started. It is not possible to change after startup. When calling tput/2, tigetnum/1 and tigetflag/1 you should provide the name of the capability you want. It's giving directory energy. 👑

Example:

1> io_ansi:tinfo().
#{ bool => [#{code => "xr",name => "OTxr",full_name => "return_does_clr_eol"} | ...],
   str => [#{code => "bx",name => "box1",full_name => "box_chars_1"} | ...],
   num => [#{code => "kn",name => "OTkn", full_name => "number_of_function_keys"} | ...]
}

🔥 tput/2 — make the terminal do the thing 🔥

tput(TermInfoCapName :: string(), Args :: [integer()]) ->
              unicode:unicode_binary().

Returns the string representing the action taken by the given terminal capability. The names of the terminal capabilities can be found in the terminfo documentation, or by calling tinfo/0. tput/2 will use the terminfo definition associated with the TERM environment variable when the Erlang VM is started. It is not possible to change after startup. If the given capability is not defined in the terminfo database an enotsup error is generated, if the given capability is invalid a badarg error is generated. This function does not work on Windows and will always generate a badarg exception. Periodt. 💀

Example:

%% Set the foreground color to 3
1> io_ansi:tput("setaf",[3]).
<<"\e[33m">>
%% Move the cursor up 2 spaces
2> io_ansi:tput("cuu",[2]).
<<"\e[2A">>
%% Move the cursor down 1 space
3> io_ansi:tput("cud1").
<<"\n">>
%% unsupported capability
4> io_ansi:tput("slm").
** exception error: {enotsup,"slm"}
     in function  io_ansi:tput/2
%% unknown capability
5> io_ansi:tput("foobar").
** exception error: {einval,"foobar",[]}
     in function  io_ansi:tput/2

✨ underline/0 — underline mode, slay ✨

underline() -> unicode:chardata().

Turn on underline text style. That's it, that's the post. 💅

Example:

1> io_ansi:underline().
<<"\e[4m">>

🌸 underline_color/1 — underline color by atom or index 🌸

underline_color(Index :: 0..255 | color_atom()) ->
                         unicode:chardata().

Set underline color to a named color or index color. Not widely supported. Accepts color atoms (red, blue, light_green, etc.) or index colors (0-255). Index 0-15 correspond to the named colors in color_atom/0. Lowkey niche but cute. 🎀

Example:

1> io_ansi:underline_color(red).
<<"\e[58;5;1m">>
2> io_ansi:underline_color(light_cyan).
<<"\e[58;5;14m">>
3> io_ansi:underline_color(196).
<<"\e[58;5;196m">>

💜 underline_color/3 — RGB underline color 💜

underline_color(0..255, 0..255, 0..255) -> unicode:chardata().

Set underline color to RGB color. Not widely supported. Still iconic tho. 🌈

Example:

1> io_ansi:underline_color(255, 0, 0).
<<"\e[58;2;255;0;0m">>

🎀 underline_off/0 — underline off, we're done 🎀

underline_off() -> unicode:chardata().

Turn off underline text style. The vibes are calm again. 🫶

Example:

1> io_ansi:underline_off().
<<"\e[24m">>

🤍 white/0 — foreground white, main character energy 🤍

white() -> unicode:chardata().

Change foreground (aka text) color to white. Clean, crisp, no notes. ✨

Example:

1> io_ansi:white().
<<"\e[37m">>

🤍 white_background/0 — background white, soft launch 🤍

white_background() -> unicode:chardata().

Change background color to white. It's giving blank canvas. 🎨

Example:

1> io_ansi:white_background().
<<"\e[47m">>

🤍 white_underline/0 — underline white, not widely supported 🤍

white_underline() -> unicode:chardata().

Change underline color to white. Not widely supported. We still stan. 💖

Example:

1> io_ansi:white_underline().
<<"\e[58;5;7m">>

💛 yellow/0 — foreground yellow, sunshine vibes 💛

yellow() -> unicode:chardata().

Change foreground (aka text) color to yellow. Golden hour energy. 🌞

Example:

1> io_ansi:yellow().
<<"\e[33m">>

💛 yellow_background/0 — background yellow, highlighter realness 💛

yellow_background() -> unicode:chardata().

Change background color to yellow. No cap, very loud, very fun. ✨

Example:

1> io_ansi:yellow_background().
<<"\e[43m">>

💛 yellow_underline/0 — underline yellow, not widely supported 💛

yellow_underline() -> unicode:chardata().

Change underline color to yellow. Not widely supported. But if your terminal ate, it ate. 💅

Example:

1> io_ansi:yellow_underline().
<<"\e[58;5;3m">>

And that's the whole io_ansi(3) page, bestie. Huge kisses to Ericsson AB for the source, stdlib 8.0.4 for the version, and the date — wherever it's hiding in the footer, it's getting its flowers too. Periodt. 💖✨🦋

📦 where this page comes from