-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"]).
%% ├──┤
ok

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

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

Activate the alternate screen.

Example:

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

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

Deactivate the alternate screen.

Example:

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

-spec background(Index :: 0..255 | 0..87) -> 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">>

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

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

Change foreground (aka text) color to black.

Example:

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

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

Change background color to black.

Example:

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

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

Change foreground (aka text) color to blue.

Example:

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

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

Change background color to blue.

Example:

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

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

Turn on bold text style.

Example:

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

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

Turn off bold text style.

Example:

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

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

Clear screen and set cursor to home.

Example:

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

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

Change foreground (aka text) color to index color. Index 0-15 are equivilant 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">>

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

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

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

Move the cursor backward N characters.

Example:

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

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

Move the cursor backward N characters.

Example:

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

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

Move the cursor down one line.

Example:

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

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

Move the cursor down N lines.

Example:

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

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

Move the cursor forward one character.

Example:

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

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

Move the cursor forward N characters.

Example:

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

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

Hide the cursor.

Example:

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

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

Move the cursor to the start of the current line.

Example:

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

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

Move the cursor to column X.

Example:

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

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

Move the cursor to line X and column Y.

Example:

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

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

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

Example:

1> io_ansi:cursor_next_line().
<<"\eE">>

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

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

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

Restore a saved cursor position.

Example:

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

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

Save the current cursor position.

Example:

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

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

Show the cursor.

Example:

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

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

Move the cursor up one line.

Example:

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

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

Move the cursor up N lines.

Example:

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

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

Move the cursor to line X.

Example:

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

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

Change foreground (aka text) color to cyan.

Example:

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

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

Change background color to cyan.

Example:

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

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

Change background color to the default color.

Example:

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

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

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

Example:

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

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

Delete 1 character at cursor.

Example:

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

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

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

Delete 1 line at cursor.

Example:

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

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

Delete Lines lines at cursor.

Example:

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

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

-spec enabled() -> boolean().

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

Example:

1> io_ansi:enabled().
true

-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

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

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

Clear screen after cursor.

Example:

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

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

Erase line at cursor.

Example:

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

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

Equivalent to format(Format, []).

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

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

-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, except that it also allows atoms and tuples represeting 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.

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([invalid_code, "Hello world"]).
** exception error: {invalid_code,invalid_code}
     in function  io_ansi:format_internal/3

For a detailed description of the available formatting options, see io:fwrite/3.

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

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

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

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

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

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

-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}}
     in function  io_ansi:fwrite/4
        called as io_ansi:fwrite(standard_io,[invalid_code,"%% Hello ~p\n"],[world],[])

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.

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

Change foreground (aka text) color to green.

Example:

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

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

Change background color to green.

Example:

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

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

Stop emitting a hyperlink.

Example:

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

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

Equivalent to hyperlink_start(URL, []).

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

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

Insert Chars at cursor.

Example:

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

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

Insert 1 line at cursor.

Example:

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

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

Insert Lines lines at cursor.

Example:

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

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

Enable keypad transmit mode.

Example:

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

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

Disable keypad transmit mode.

Example:

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

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

Change foreground (aka text) color to light black.

Example:

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

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

Change background color to light black.

Example:

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

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

Change foreground (aka text) color to light blue.

Example:

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

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

Change background color to light blue.

Example:

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

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

Change foreground (aka text) color to light cyan.

Example:

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

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

Change background color to light cyan.

Example:

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

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

Change foreground (aka text) color to light green.

Example:

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

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

Change background color to light green.

Example:

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

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

Change foreground (aka text) color to light magenta.

Example:

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

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

Change background color to light magenta.

Example:

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

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

Change foreground (aka text) color to light red.

Example:

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

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

Change background color to light red.

Example:

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

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

Change foreground (aka text) color to light white.

Example:

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

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

Change background color to light white.

Example:

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

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

Change foreground (aka text) color to light yellow.

Example:

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

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

Change background color to light yellow.

Example:

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

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

Change foreground (aka text) color to magenta.

Example:

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

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

Change background color to magenta.

Example:

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

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

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

Turn on negative text style.

Example:

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

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

Turn off negative text style.

Example:

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

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

Change foreground (aka text) color to red.

Example:

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

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

Change background color to red.

Example:

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

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

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

-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]

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

Scroll the screen backward 1 step.

Example:

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

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

Scroll the screen backward N step.

Example:

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

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

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

Scroll the screen forward 1 step.

Example:

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

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

Scroll the screen forward N step.

Example:

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

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

Move cursor one tab forward.

Example:

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

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

Move cursor one tab backward.

Example:

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

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

Clear any tab location at the current cursor location.

Example:

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

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

Clear all tab locations.

Example:

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

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

Set a new tab location at the current cursor location.

Example:

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

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

Turn on underline text style.

Example:

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

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

Turn off underline text style.

Example:

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

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

Change foreground (aka text) color to white.

Example:

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

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

Change background color to white.

Example:

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

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

Change foreground (aka text) color to yellow.

Example:

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

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

Change background color to yellow.

Example:

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