io_ansi — stdlib v8.0.2

Search documentation of stdlib

# io_ansi (stdlib v8.0.2)

Copy Markdown View Source

Controlling the terminal using virtual terminal sequences (aka ANSI escape codes).

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.

## Summary

### Types

background_color()

Virtual terminal sequences that control the background color.

color()

Virtual terminal sequences that control color.

color_atom()
cursor()

Virtual terminal sequences that controls the cursor.

foreground_color()

Virtual terminal sequences that control the foreground (aka text) color.

format()

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

hyperlink()

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

hyperlink_params()
input()

Virtual terminal sequences for cursor input.

option()
options()
style()

Virtual terminal sequences that control text style.

tab()

Virtual terminal sequences that works with tabs.

text()

Virtual terminal sequences that works on text.

text_formatting()

Virtual terminal sequences that control text formatting.

text_modification()

Virtual terminal sequences that can erase or overwrite text.

underline_color()

Virtual terminal sequences that control underline color.

underline_style()

Virtual terminal sequences that control underline style.

vts()

Virtual terminal sequences.

window()

Virtual terminal sequences that controls the screen.

### Functions

alternate_character_set_mode()

Enable the alternate characters set mode

alternate_character_set_mode_off()

Disable the alternate characters set mode

alternate_screen()

Activate the alternate screen buffer.

alternate_screen_off()

Deactivate the alternate screen.

background(Index)

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.

background(Red, Green, Blue)

Change background color to RGB color.

black()

Change foreground (aka text) color to black.

black_background()

Change background color to black.

black_underline()

Change underline color to black. Not widely supported.

blink()

Turn on blink text style. Not widely supported.

blink_off()

Turn off blink text style.

blue()

Change foreground (aka text) color to blue.

blue_background()

Change background color to blue.

blue_underline()

Change underline color to blue. Not widely supported.

bold()

Turn on bold text style.

bold_off()

Turn off bold text style.

clear()

Clear screen and set cursor to home.

color(Index)

Change foreground (aka text) color to index color. `Index` 0-15 are equivalent to the named colors in `foreground_color/0` in the order that they are listed.

color(Red, Green, Blue)

Change foreground (aka text) color to RGB color.

color_name_to_index(Color)

Convert a color atom to its corresponding index (0-15).

curly_underline()

Turn on curly underline text style. Not widely supported.

cursor(Line, Column)

Move the cursor to the given position. Position 0,0 is at the top left of the terminal.

cursor_backward()

Move the cursor backward `N` characters.

cursor_backward(N)

Move the cursor backward `N` characters.

cursor_down()

Move the cursor down one line.

cursor_down(N)

Move the cursor down `N` lines.

cursor_forward()

Move the cursor forward one character.

cursor_forward(N)

Move the cursor forward `N` characters.

cursor_get_position()

Get the current cursor position as {Row, Column}. Example

cursor_hide()

Hide the cursor.

cursor_home()

Move the cursor to the start of the current line.

cursor_horizontal_absolute(X)

Move the cursor to column `X`.

cursor_horizontal_vertical(X, Y)

Move the cursor to line `X` and column `Y`. Position 1,1 is at the top left of the terminal.

cursor_move(DeltaLine, DeltaColumn)

Move the cursor relative to its current position.

cursor_next_line()

Move the cursor down one line and then returns it to home.

cursor_previous_line()

Move the cursor up one line and then returns it to home.

cursor_report_position()

Instruct the terminal to report the current cursor position.

cursor_restore()

Restore a saved cursor position.

cursor_save()

Save the current cursor position.

cursor_show()

Show the cursor.

cursor_up()

Move the cursor up one line.

cursor_up(N)

Move the cursor up `N` lines.

cursor_vertical_absolute(X)

Move the cursor to line `X`.

cyan()

Change foreground (aka text) color to cyan.

cyan_background()

Change background color to cyan.

cyan_underline()

Change underline color to cyan. Not widely supported.

dashed_underline()

Turn on dashed underline text style. Not widely supported.

default_background()

Change background color to the default color.

default_color()

Change foreground (aka text) color to the default color.

default_underline_color()

Reset underline color to the default.

delete_character()

Delete 1 character at cursor.

delete_character(Chars)

Delete `Chars` characters at cursor by shifting the text `Chars` characters to the left.

delete_line()

Delete 1 line at cursor.

delete_line(Lines)

Delete `Lines` lines at cursor.

device_report_attributes()

Tell the terminal emulator to report its device attributes.

dim()

Turn on dim text style. Not widely supported.

dim_off()

Turn off dim text style.

dotted_underline()

Turn on dotted underline text style. Not widely supported.

double_underline()

Turn on double underline text style. Not widely supported.

enabled()

Check if `io:user/0` can interpret ANSI escape sequences.

enabled(Device)

Check if `Device` can interpret ANSI escape sequences.

erase_character(Chars)

Erase `Chars` characters at cursor by making `Chars` characters before the cursor blank.

erase_display()

Clear screen after cursor.

erase_line()

Erase line at cursor.

format(Format)

Equivalent to `format(Format, [])`.

format(Format, Data)

Equivalent to `format(Format, Data, [])`.

format(Format, Data, Options)

Returns a character list that represents `Data` formatted in accordance with `Format`.

fwrite(Format)

Equivalent to `fwrite(standard_io, Format, [], [])`.

fwrite(Format, Data)

Equivalent to `fwrite(standard_io, Format, Data, [])`.

fwrite(Format, Data, Options)

Equivalent to `fwrite(standard_io, Format, Data, Options)`.

fwrite(Device, Format, Data, Options)

Writes the items in `Data` on the `IoDevice` in accordance with `Format`.

green()

Change foreground (aka text) color to green.

green_background()

Change background color to green.

green_underline()

Change underline color to green. Not widely supported.

hyperlink_reset()

Stop emitting a hyperlink.

hyperlink_start(URL)

Equivalent to `hyperlink_start(URL, [])`.

hyperlink_start(URL, Params)

Start a hyperlink pointing to the given `URL` using `Params`.

insert_character(Chars)

Insert `Chars` at cursor.

insert_line()

Insert 1 line at cursor.

insert_line(Lines)

Insert `Lines` lines at cursor.

inverse()

Turn on inverse text style.

inverse_off()

Turn off inverse text style.

invisible()

Turn on invisible text style. Not widely supported.

invisible_off()

Turn off invisible text style.

italic()

Turn on italic text style. Not widely supported.

italic_off()

Turn off italic text style.

keypad_transmit_mode()

Enable keypad transmit mode.

keypad_transmit_mode_off()

Disable keypad transmit mode.

light_black()

Change foreground (aka text) color to light black.

light_black_background()

Change background color to light black.

light_black_underline()

Change underline color to light black. Not widely supported.

light_blue()

Change foreground (aka text) color to light blue.

light_blue_background()

Change background color to light blue.

light_blue_underline()

Change underline color to light blue. Not widely supported.

light_cyan()

Change foreground (aka text) color to light cyan.

light_cyan_background()

Change background color to light cyan.

light_cyan_underline()

Change underline color to light cyan. Not widely supported.

light_green()

Change foreground (aka text) color to light green.

light_green_background()

Change background color to light green.

light_green_underline()

Change underline color to light green. Not widely supported.

light_magenta()

Change foreground (aka text) color to light magenta.

light_magenta_background()

Change background color to light magenta.

light_magenta_underline()

Change underline color to light magenta. Not widely supported.

light_red()

Change foreground (aka text) color to light red.

light_red_background()

Change background color to light red.

light_red_underline()

Change underline color to light red. Not widely supported.

light_white()

Change foreground (aka text) color to light white.

light_white_background()

Change background color to light white.

light_white_underline()

Change underline color to light white. Not widely supported.

light_yellow()

Change foreground (aka text) color to light yellow.

light_yellow_background()

Change background color to light yellow.

light_yellow_underline()

Change underline color to light yellow. Not widely supported.

magenta()

Change foreground (aka text) color to magenta.

magenta_background()

Change background color to magenta.

magenta_underline()

Change underline color to magenta. Not widely supported.

modify_color(Index, R, G, B)

Modify the color referenced by `Index` to be RGB.

overline()

Turn on overline text style.

overline_off()

Turn off overline text style.

red()

Change foreground (aka text) color to red.

red_background()

Change background color to red.

red_underline()

Change underline color to red. Not widely supported.

render(Data)

Equivalent to `render(Data, [])`.

render(Data, Options)

Renders terminal sequences in `Data`.

reset()

Reset virtual terminal sequences to their original state.

reverse_index()

Move the cursor up one line, but keeps the cursor on the same location on the screen by scrolling the screen down.

scan(Data)

Scan the string for virtial terminal sequences.

scroll_backward()

Scroll the screen backward 1 step.

scroll_backward(Steps)

Scroll the screen backward `N` step.

scroll_change_region(Line1, Line2)

Change the scolling region to be from `Line1` to `Line2`.

scroll_forward()

Scroll the screen forward 1 step.

scroll_forward(N)

Scroll the screen forward `N` step.

strikethrough()

Turn on strikethrough text style. Not widely supported.

strikethrough_off()

Turn off strikethrough text style.

tab()

Move cursor one tab forward.

tab_backward()

Move cursor one tab backward.

tab_clear()

Clear any tab location at the current cursor location.

tab_clear_all()

Clear all tab locations.

tab_set()

Set a new tab location at the current cursor location.

underline()

Turn on underline text style.

underline_color(Index)

Set underline color to a named color or index color. Not widely supported.

underline_color(Red, Green, Blue)

Set underline color to RGB color. Not widely supported.

underline_off()

Turn off underline text style.

white()

Change foreground (aka text) color to white.

white_background()

Change background color to white.

white_underline()

Change underline color to white. Not widely supported.

yellow()

Change foreground (aka text) color to yellow.

yellow_background()

Change background color to yellow.

yellow_underline()

Change underline color to yellow. Not widely supported.

### Functions: terminfo

tigetflag(TermInfoCapName)

Returns true if the terminfo capability is available, otherwise false.

tigetnum(TermInfoCapName)

Returns the number representing a terminfo capability.

tinfo()

Returns information about all available terminfo capabilities. See the terminfo documentation for details on each.

tput(TermInfoCap)

Equivalent to `tput(TermInfoCap, [])`.

tput(TermInfoCapName, Args)

Returns the string representing the action taken by the given terminal capability.

## Types

# background_color()

(not exported) (since OTP 29.0)

    -type 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.

# color()

(not exported) (since OTP 29.0)

    -type 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.

# color_atom()

(not exported) (since OTP 29.0)

    -type 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.

# cursor()

(not exported) (since OTP 29.0)

    -type 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.

# foreground_color()

(not exported) (since OTP 29.0)

    -type 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.

# format()

(not exported) (since OTP 29.0)

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

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

# hyperlink()

(not exported) (since OTP 29.0)

    -type 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.

# hyperlink_params()

(not exported) (since OTP 29.0)

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

# input()

(not exported) (since OTP 29.0)

    -type 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.

# option()

(not exported) (since OTP 29.0)

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

# options()

(not exported) (since OTP 29.0)

    -type options() :: [option()].

# style()

(not exported) (since OTP 29.0)

    -type 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.

# tab()

(not exported) (since OTP 29.0)

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

Virtual terminal sequences that works with tabs.

# text()

(not exported) (since OTP 29.0)

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

Virtual terminal sequences that works on text.

# text_formatting()

(not exported) (since OTP 29.0)

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

Virtual terminal sequences that control text formatting.

# text_modification()

(not exported) (since OTP 29.0)

    -type 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.

# underline_color()

(not exported) (since OTP 29.0)

    -type 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_style()

(not exported) (since OTP 29.0)

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

Virtual terminal sequences that control underline style.

# vts()

(since OTP 29.0)

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

Virtual terminal sequences.

# window()

(not exported) (since OTP 29.0)

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

Virtual terminal sequences that controls the screen.

## Functions

# alternate_character_set_mode()

(since OTP 29.0)

    -spec alternate_character_set_mode() -> unicode:chardata().

Enable the alternate characters set mode

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()

(since OTP 29.0)

    -spec alternate_character_set_mode_off() -> unicode:chardata().

Disable the alternate characters set mode

Example:

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

# alternate_screen()

(since OTP 29.0)

    -spec 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()

(since OTP 29.0)

    -spec alternate_screen_off() -> unicode:chardata().

Deactivate the alternate screen.

Example:

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

# background(Index)

(since OTP 29.0)

    -spec 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(Red, Green, Blue)

(since OTP 29.0)

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

Change background color to RGB color.

Example:

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

# black()

(since OTP 29.0)

    -spec black() -> unicode:chardata().

Change foreground (aka text) color to black.

Example:

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

# black_background()

(since OTP 29.0)

    -spec black_background() -> unicode:chardata().

Change background color to black.

Example:

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

# black_underline()

(since OTP 29.0)

    -spec black_underline() -> unicode:chardata().

Change underline color to black. Not widely supported.

Example:

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

# blink()

(since OTP 29.0)

    -spec blink() -> unicode:chardata().

Turn on blink text style. Not widely supported.

Example:

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

# blink_off()

(since OTP 29.0)

    -spec blink_off() -> unicode:chardata().

Turn off blink text style.

Example:

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

# blue()

(since OTP 29.0)

    -spec blue() -> unicode:chardata().

Change foreground (aka text) color to blue.

Example:

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

# blue_background()

(since OTP 29.0)

    -spec blue_background() -> unicode:chardata().

Change background color to blue.

Example:

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

# blue_underline()

(since OTP 29.0)

    -spec blue_underline() -> unicode:chardata().

Change underline color to blue. Not widely supported.

Example:

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

# bold()

(since OTP 29.0)

    -spec bold() -> unicode:chardata().

Turn on bold text style.

Example:

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

# bold_off()

(since OTP 29.0)

    -spec bold_off() -> unicode:chardata().

Turn off bold text style.

Example:

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

# clear()

(since OTP 29.0)

    -spec clear() -> unicode:chardata().

Clear screen and set cursor to home.

Example:

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

# color(Index)

(since OTP 29.0)

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

Change foreground (aka text) color to index color. `Index` 0-15 are equivalent to the named colors in `foreground_color/0` in the order that they are listed.

Example:

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

# color(Red, Green, Blue)

(since OTP 29.0)

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

Change foreground (aka text) color to RGB color.

Example:

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

# color_name_to_index(Color)

(since OTP 29.0)

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

Convert a color atom to its corresponding index (0-15).

Example:

    1> io_ansi:color_name_to_index(red).
    1

# curly_underline()

(since OTP 29.0)

    -spec curly_underline() -> unicode:chardata().

Turn on curly underline text style. Not widely supported.

Example:

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

# cursor(Line, Column)

(since OTP 29.0)

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

Move the cursor to the given position. Position 0,0 is at the top left of the terminal.

Example:

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

# cursor_backward()

(since OTP 29.0)

    -spec cursor_backward() -> unicode:chardata().

Move the cursor backward `N` characters.

Example:

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

# cursor_backward(N)

(since OTP 29.0)

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

Move the cursor backward `N` characters.

Example:

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

# cursor_down()

(since OTP 29.0)

    -spec cursor_down() -> unicode:chardata().

Move the cursor down one line.

Example:

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

# cursor_down(N)

(since OTP 29.0)

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

Move the cursor down `N` lines.

Example:

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

# cursor_forward()

(since OTP 29.0)

    -spec cursor_forward() -> unicode:chardata().

Move the cursor forward one character.

Example:

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

# cursor_forward(N)

(since OTP 29.0)

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

Move the cursor forward `N` characters.

Example:

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

# cursor_get_position()

(since OTP 29.0)

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

Get the current cursor position as {Row, Column}. 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()

(since OTP 29.0)

    -spec cursor_hide() -> unicode:chardata().

Hide the cursor.

Example:

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

# cursor_home()

(since OTP 29.0)

    -spec cursor_home() -> unicode:chardata().

Move the cursor to the start of the current line.

Example:

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

# cursor_horizontal_absolute(X)

(since OTP 29.0)

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

Move the cursor to column `X`.

Example:

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

# cursor_horizontal_vertical(X, Y)

(since OTP 29.0)

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

Move the cursor to line `X` and column `Y`. Position 1,1 is at the top left of the terminal.

Example:

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

# cursor_move(DeltaLine, DeltaColumn)

(since OTP 29.0)

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

Move the cursor relative to its current position.

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()

(since OTP 29.0)

    -spec cursor_next_line() -> unicode:chardata().

Move the cursor down one line and then returns it to home.

Example:

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

# cursor_previous_line()

(since OTP 29.0)

    -spec cursor_previous_line() -> unicode:chardata().

Move the cursor up one line and then returns it to home.

Example:

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

# cursor_report_position()

(since OTP 29.0)

    -spec cursor_report_position() -> unicode:chardata().

Instruct the terminal to report the current cursor position.

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 the example is row 58 and column 1 both are 1 index based.

# cursor_restore()

(since OTP 29.0)

    -spec cursor_restore() -> unicode:chardata().

Restore a saved cursor position.

Example:

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

# cursor_save()

(since OTP 29.0)

    -spec cursor_save() -> unicode:chardata().

Save the current cursor position.

Example:

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

# cursor_show()

(since OTP 29.0)

    -spec cursor_show() -> unicode:chardata().

Show the cursor.

Example:

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

# cursor_up()

(since OTP 29.0)

    -spec cursor_up() -> unicode:chardata().

Move the cursor up one line.

Example:

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

# cursor_up(N)

(since OTP 29.0)

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

Move the cursor up `N` lines.

Example:

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

# cursor_vertical_absolute(X)

(since OTP 29.0)

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

Move the cursor to line `X`.

Example:

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

# cyan()

(since OTP 29.0)

    -spec cyan() -> unicode:chardata().

Change foreground (aka text) color to cyan.

Example:

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

# cyan_background()

(since OTP 29.0)

    -spec cyan_background() -> unicode:chardata().

Change background color to cyan.

Example:

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

# cyan_underline()

(since OTP 29.0)

    -spec cyan_underline() -> unicode:chardata().

Change underline color to cyan. Not widely supported.

Example:

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

# dashed_underline()

(since OTP 29.0)

    -spec dashed_underline() -> unicode:chardata().

Turn on dashed underline text style. Not widely supported.

Example:

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

# default_background()

(since OTP 29.0)

    -spec default_background() -> unicode:chardata().

Change background color to the default color.

Example:

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

# default_color()

(since OTP 29.0)

    -spec default_color() -> unicode:chardata().

Change foreground (aka text) color to the default color.

Example:

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

# default_underline_color()

(since OTP 29.0)

    -spec default_underline_color() -> unicode:chardata().

Reset underline color to the default.

Example:

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

# delete_character()

(since OTP 29.0)

    -spec delete_character() -> unicode:chardata().

Delete 1 character at cursor.

Example:

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

# delete_character(Chars)

(since OTP 29.0)

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

Delete `Chars` characters at cursor by shifting the text `Chars` characters to the left.

Example:

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

# delete_line()

(since OTP 29.0)

    -spec delete_line() -> unicode:chardata().

Delete 1 line at cursor.

Example:

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

# delete_line(Lines)

(since OTP 29.0)

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

Delete `Lines` lines at cursor.

Example:

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

# device_report_attributes()

(since OTP 29.0)

    -spec device_report_attributes() -> unicode:chardata().

Tell the terminal emulator to report its device attributes.

Examples:

    1> io_ansi:device_report_attributes().
    <<"\e[0c">>

    ## 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"

# dim()

(since OTP 29.0)

    -spec dim() -> unicode:chardata().

Turn on dim text style. Not widely supported.

Example:

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

# dim_off()

(since OTP 29.0)

    -spec dim_off() -> unicode:chardata().

Turn off dim text style.

Example:

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

# dotted_underline()

(since OTP 29.0)

    -spec dotted_underline() -> unicode:chardata().

Turn on dotted underline text style. Not widely supported.

Example:

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

# double_underline()

(since OTP 29.0)

    -spec double_underline() -> unicode:chardata().

Turn on double underline text style. Not widely supported.

Example:

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

# enabled()

(since OTP 29.0)

    -spec enabled() -> boolean().

Check if `io:user/0` can interpret ANSI escape sequences.

Example:

    1> io_ansi:enabled().
    true

# enabled(Device)

(since OTP 29.0)

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

Check if `Device` can interpret ANSI escape sequences.

This is done by checking if `Device` represents a terminal and if the `TERM` environment variable is set to a terminal type that supports virtual terminal sequences.

Example:

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

# erase_character(Chars)

(since OTP 29.0)

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

Erase `Chars` characters at cursor by making `Chars` characters before the cursor blank.

Example:

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

# erase_display()

(since OTP 29.0)

    -spec erase_display() -> unicode:chardata().

Clear screen after cursor.

Example:

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

# erase_line()

(since OTP 29.0)

    -spec erase_line() -> unicode:chardata().

Erase line at cursor.

Example:

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

# format(Format)

(since OTP 29.0)

    -spec format(format()) -> unicode:unicode_binary().

Equivalent to `format(Format, [])`.

# format(Format, Data)

(since OTP 29.0)

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

Equivalent to `format(Format, Data, [])`.

# format(Format, Data, Options)

(since OTP 29.0)

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

Returns a character list that represents `Data` formatted in accordance with `Format`.

This function works just as `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.

Calling `format/3` will always emit a `reset/0` VTS at the end of the returned string. To not emit this, set the `reset` option to `false`.

To force enabling or disabling of 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.

To 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(Format)

(since OTP 29.0)

    -spec fwrite(Format :: format()) -> ok.

Equivalent to `fwrite(standard_io, Format, [], [])`.

# fwrite(Format, Data)

(since OTP 29.0)

    -spec fwrite(Format :: format(), [term()]) -> ok.

Equivalent to `fwrite(standard_io, Format, Data, [])`.

# fwrite(Format, Data, Options)

(since OTP 29.0)

    -spec fwrite(Format :: format(), [term()], options()) -> ok.

Equivalent to `fwrite(standard_io, Format, Data, Options)`.

# fwrite(Device, Format, Data, Options)

(since OTP 29.0)

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

Writes the items in `Data` on the `IoDevice` in accordance with `Format`.

This function 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 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 what each VTS should be converted to is done by the destination I/O device. This means that if the I/O device is on a remote node, the terminfo database loaded into that remote node will be used.

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 if the device does not support a certain VTS. If you want to force usage of VTSs you can pass `{enabled, true}` and that will use the local defintions to translate.

# green()

(since OTP 29.0)

    -spec green() -> unicode:chardata().

Change foreground (aka text) color to green.

Example:

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

# green_background()

(since OTP 29.0)

    -spec green_background() -> unicode:chardata().

Change background color to green.

Example:

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

# green_underline()

(since OTP 29.0)

    -spec green_underline() -> unicode:chardata().

Change underline color to green. Not widely supported.

Example:

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

# hyperlink_reset()

(since OTP 29.0)

    -spec hyperlink_reset() -> unicode:chardata().

Stop emitting a hyperlink.

Example:

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

# hyperlink_start(URL)

(since OTP 29.0)

    -spec hyperlink_start(uri_string:uri_string()) -> unicode:chardata().

Equivalent to `hyperlink_start(URL, [])`.

# hyperlink_start(URL, Params)

(since OTP 29.0)

    -spec hyperlink_start(uri_string:uri_string(),
                          [{Key :: unicode:chardata(), Value :: unicode:chardata()}]) ->
                             unicode:chardata().

Start 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)

(since OTP 29.0)

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

Insert `Chars` at cursor.

Example:

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

# insert_line()

(since OTP 29.0)

    -spec insert_line() -> unicode:chardata().

Insert 1 line at cursor.

Example:

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

# insert_line(Lines)

(since OTP 29.0)

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

Insert `Lines` lines at cursor.

Example:

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

# inverse()

(since OTP 29.0)

    -spec inverse() -> unicode:chardata().

Turn on inverse text style.

Inverse is also called reverse video or standout mode.

Example:

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

# inverse_off()

(since OTP 29.0)

    -spec inverse_off() -> unicode:chardata().

Turn off inverse text style.

Inverse is also called reverse video or standout mode.

Example:

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

# invisible()

(since OTP 29.0)

    -spec invisible() -> unicode:chardata().

Turn on invisible text style. Not widely supported.

Example:

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

# invisible_off()

(since OTP 29.0)

    -spec invisible_off() -> unicode:chardata().

Turn off invisible text style.

Example:

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

# italic()

(since OTP 29.0)

    -spec italic() -> unicode:chardata().

Turn on italic text style. Not widely supported.

Example:

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

# italic_off()

(since OTP 29.0)

    -spec italic_off() -> unicode:chardata().

Turn off italic text style.

Example:

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

# keypad_transmit_mode()

(since OTP 29.0)

    -spec keypad_transmit_mode() -> unicode:chardata().

Enable keypad transmit mode.

Example:

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

# keypad_transmit_mode_off()

(since OTP 29.0)

    -spec keypad_transmit_mode_off() -> unicode:chardata().

Disable keypad transmit mode.

Example:

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

# light_black()

(since OTP 29.0)

    -spec light_black() -> unicode:chardata().

Change foreground (aka text) color to light black.

Example:

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

# light_black_background()

(since OTP 29.0)

    -spec light_black_background() -> unicode:chardata().

Change background color to light black.

Example:

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

# light_black_underline()

(since OTP 29.0)

    -spec light_black_underline() -> unicode:chardata().

Change underline color to light black. Not widely supported.

Example:

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

# light_blue()

(since OTP 29.0)

    -spec light_blue() -> unicode:chardata().

Change foreground (aka text) color to light blue.

Example:

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

# light_blue_background()

(since OTP 29.0)

    -spec light_blue_background() -> unicode:chardata().

Change background color to light blue.

Example:

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

# light_blue_underline()

(since OTP 29.0)

    -spec light_blue_underline() -> unicode:chardata().

Change underline color to light blue. Not widely supported.

Example:

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

# light_cyan()

(since OTP 29.0)

    -spec light_cyan() -> unicode:chardata().

Change foreground (aka text) color to light cyan.

Example:

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

# light_cyan_background()

(since OTP 29.0)

    -spec light_cyan_background() -> unicode:chardata().

Change background color to light cyan.

Example:

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

# light_cyan_underline()

(since OTP 29.0)

    -spec light_cyan_underline() -> unicode:chardata().

Change underline color to light cyan. Not widely supported.

Example:

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

# light_green()

(since OTP 29.0)

    -spec light_green() -> unicode:chardata().

Change foreground (aka text) color to light green.

Example:

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

# light_green_background()

(since OTP 29.0)

    -spec light_green_background() -> unicode:chardata().

Change background color to light green.

Example:

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

# light_green_underline()

(since OTP 29.0)

    -spec light_green_underline() -> unicode:chardata().

Change underline color to light green. Not widely supported.

Example:

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

# light_magenta()

(since OTP 29.0)

    -spec light_magenta() -> unicode:chardata().

Change foreground (aka text) color to light magenta.

Example:

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

# light_magenta_background()

(since OTP 29.0)

    -spec light_magenta_background() -> unicode:chardata().

Change background color to light magenta.

Example:

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

# light_magenta_underline()

(since OTP 29.0)

    -spec light_magenta_underline() -> unicode:chardata().

Change underline color to light magenta. Not widely supported.

Example:

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

# light_red()

(since OTP 29.0)

    -spec light_red() -> unicode:chardata().

Change foreground (aka text) color to light red.

Example:

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

# light_red_background()

(since OTP 29.0)

    -spec light_red_background() -> unicode:chardata().

Change background color to light red.

Example:

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

# light_red_underline()

(since OTP 29.0)

    -spec light_red_underline() -> unicode:chardata().

Change underline color to light red. Not widely supported.

Example:

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

# light_white()

(since OTP 29.0)

    -spec light_white() -> unicode:chardata().

Change foreground (aka text) color to light white.

Example:

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

# light_white_background()

(since OTP 29.0)

    -spec light_white_background() -> unicode:chardata().

Change background color to light white.

Example:

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

# light_white_underline()

(since OTP 29.0)

    -spec light_white_underline() -> unicode:chardata().

Change underline color to light white. Not widely supported.

Example:

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

# light_yellow()

(since OTP 29.0)

    -spec light_yellow() -> unicode:chardata().

Change foreground (aka text) color to light yellow.

Example:

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

# light_yellow_background()

(since OTP 29.0)

    -spec light_yellow_background() -> unicode:chardata().

Change background color to light yellow.

Example:

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

# light_yellow_underline()

(since OTP 29.0)

    -spec light_yellow_underline() -> unicode:chardata().

Change underline color to light yellow. Not widely supported.

Example:

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

# magenta()

(since OTP 29.0)

    -spec magenta() -> unicode:chardata().

Change foreground (aka text) color to magenta.

Example:

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

# magenta_background()

(since OTP 29.0)

    -spec magenta_background() -> unicode:chardata().

Change background color to magenta.

Example:

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

# magenta_underline()

(since OTP 29.0)

    -spec magenta_underline() -> unicode:chardata().

Change underline color to magenta. Not widely supported.

Example:

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

# modify_color(Index, R, G, B)

(since OTP 29.0)

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

Modify the color referenced by `Index` to be RGB.

Calling this function for `Index` 0-15 will change the color of the named colors in `foreground_color/0` and `background_color/0`.

Example:

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

# overline()

(since OTP 29.0)

    -spec overline() -> unicode:chardata().

Turn on overline text style.

Example:

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

# overline_off()

(since OTP 29.0)

    -spec overline_off() -> unicode:chardata().

Turn off overline text style.

Example:

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

# red()

(since OTP 29.0)

    -spec red() -> unicode:chardata().

Change foreground (aka text) color to red.

Example:

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

# red_background()

(since OTP 29.0)

    -spec red_background() -> unicode:chardata().

Change background color to red.

Example:

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

# red_underline()

(since OTP 29.0)

    -spec red_underline() -> unicode:chardata().

Change underline color to red. Not widely supported.

Example:

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

# render(Data)

(since OTP 29.0)

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

Equivalent to `render(Data, [])`.

# render(Data, Options)

(since OTP 29.0)

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

Renders terminal sequences in `Data`.

`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()

(since OTP 29.0)

    -spec reset() -> unicode:chardata().

Reset virtual terminal sequences to their original state.

This only resets the things supported by the loaded terminfo database, which means that OSCs such as `hyperlink_start/2` are not reset but have to be reset by emitting `hyperlink_reset/0`.

Example:

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

# reverse_index()

(since OTP 29.0)

    -spec reverse_index() -> unicode:chardata().

Move the cursor up one line, but keeps the cursor on the same location on the screen by scrolling the screen down.

Example:

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

# scan(Data)

(since OTP 29.0)

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

Scan the string for virtial terminal sequences.

The recognized VTSs will be 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`. This will make it easier for `io_ansi` to correctly detect arrow keys.

Any unrecognized control sequence introducers, will be 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()

(since OTP 29.0)

    -spec scroll_backward() -> unicode:chardata().

Scroll the screen backward 1 step.

Example:

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

# scroll_backward(Steps)

(since OTP 29.0)

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

Scroll the screen backward `N` step.

Example:

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

# scroll_change_region(Line1, Line2)

(since OTP 29.0)

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

Change the scolling region to be from `Line1` to `Line2`.

Example:

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

# scroll_forward()

(since OTP 29.0)

    -spec scroll_forward() -> unicode:chardata().

Scroll the screen forward 1 step.

Example:

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

# scroll_forward(N)

(since OTP 29.0)

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

Scroll the screen forward `N` step.

Example:

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

# strikethrough()

(since OTP 29.0)

    -spec strikethrough() -> unicode:chardata().

Turn on strikethrough text style. Not widely supported.

Example:

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

# strikethrough_off()

(since OTP 29.0)

    -spec strikethrough_off() -> unicode:chardata().

Turn off strikethrough text style.

Example:

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

# tab()

(since OTP 29.0)

    -spec tab() -> unicode:chardata().

Move cursor one tab forward.

Example:

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

# tab_backward()

(since OTP 29.0)

    -spec tab_backward() -> unicode:chardata().

Move cursor one tab backward.

Example:

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

# tab_clear()

(since OTP 29.0)

    -spec tab_clear() -> unicode:chardata().

Clear any tab location at the current cursor location.

Example:

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

# tab_clear_all()

(since OTP 29.0)

    -spec tab_clear_all() -> unicode:chardata().

Clear all tab locations.

Example:

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

# tab_set()

(since OTP 29.0)

    -spec tab_set() -> unicode:chardata().

Set a new tab location at the current cursor location.

Example:

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

# underline()

(since OTP 29.0)

    -spec underline() -> unicode:chardata().

Turn on underline text style.

Example:

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

# underline_color(Index)

(since OTP 29.0)

    -spec 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`.

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(Red, Green, Blue)

(since OTP 29.0)

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

Set underline color to RGB color. Not widely supported.

Example:

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

# underline_off()

(since OTP 29.0)

    -spec underline_off() -> unicode:chardata().

Turn off underline text style.

Example:

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

# white()

(since OTP 29.0)

    -spec white() -> unicode:chardata().

Change foreground (aka text) color to white.

Example:

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

# white_background()

(since OTP 29.0)

    -spec white_background() -> unicode:chardata().

Change background color to white.

Example:

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

# white_underline()

(since OTP 29.0)

    -spec white_underline() -> unicode:chardata().

Change underline color to white. Not widely supported.

Example:

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

# yellow()

(since OTP 29.0)

    -spec yellow() -> unicode:chardata().

Change foreground (aka text) color to yellow.

Example:

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

# yellow_background()

(since OTP 29.0)

    -spec yellow_background() -> unicode:chardata().

Change background color to yellow.

Example:

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

# yellow_underline()

(since OTP 29.0)

    -spec yellow_underline() -> unicode:chardata().

Change underline color to yellow. Not widely supported.

Example:

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

## Functions: terminfo

# tigetflag(TermInfoCapName)

(since OTP 29.0)

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

Returns true if the terminfo capability is available, otherwise false.

The names of the terminal capabilities can be found in the terminfo documentation, or by calling `tinfo/0`. `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.

Example:

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

# tigetnum(TermInfoCapName)

(since OTP 29.0)

    -spec 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.

Example:

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

# tinfo()

(since OTP 29.0)

    -spec 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.

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(TermInfoCap)

(since OTP 29.0)

    -spec tput(TermInfoCap :: string()) -> unicode:unicode_binary().

Equivalent to `tput(TermInfoCap, [])`.

# tput(TermInfoCapName, Args)

(since OTP 29.0)

    -spec 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.

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