Elixir
Elixir
v1.12.0

View Source IO.ANSI (Elixir v1.12.0)

Functionality to render ANSI escape sequences.

ANSI escape sequences are characters embedded in text used to control formatting, color, and other output options on video text terminals.

ANSI escapes are typically enabled on all Unix terminals. They are also available on Windows consoles from Windows 10, although it must be explicitly enabled for the current user in the registry by running the following command:

reg add HKCU\Console /v VirtualTerminalLevel /t REG_DWORD /d 1

After running the command above, you must restart your current console.

Examples

Because the ANSI escape sequences are embedded in text, the normal usage of these functions is to concatenate their output with text.

formatted_text = IO.ANSI.blue_background() <> "Example" <> IO.ANSI.reset()
IO.puts(formatted_text)

A higher level and more convenient API is also available via IO.ANSI.format/1, where you use atoms to represent each ANSI escape sequence and by default checks if ANSI is enabled:

IO.puts(IO.ANSI.format([:blue_background, "Example"]))

In case ANSI is disabled, the ANSI escape sequences are simply discarded.

Link to this section Summary

Types

ansicode()
ansidata()
ansilist()

Functions

black()

Sets foreground color to black.

black_background()

Sets background color to black.

blink_off()

Blink: off.

blink_rapid()

Blink: rapid. MS-DOS ANSI.SYS; 150 per minute or more; not widely supported.

blink_slow()

Blink: slow. Less than 150 per minute.

blue()

Sets foreground color to blue.

blue_background()

Sets background color to blue.

bright()

Bright (increased intensity) or bold.

clear()

Clears screen.

clear_line()

Clears line.

color(code)

Sets foreground color.

color(r, g, b)

Sets the foreground color from individual RGB values.

color_background(code)

Sets background color.

color_background(r, g, b)

Sets the background color from individual RGB values.

conceal()

Conceal. Not widely supported.

crossed_out()

Crossed-out. Characters legible, but marked for deletion. Not widely supported.

cursor(line, column)

Sends cursor to the absolute position specified by line and column.

cursor_down(lines \\ 1)

Sends cursor lines down.

cursor_left(columns \\ 1)

Sends cursor columns to the left.

cursor_right(columns \\ 1)

Sends cursor columns to the right.

cursor_up(lines \\ 1)

Sends cursor lines up.

cyan()

Sets foreground color to cyan.

cyan_background()

Sets background color to cyan.

default_background()

Default background color.

default_color()

Default text color.

enabled?()

Checks if ANSI coloring is supported and enabled on this machine.

encircled()

Encircled.

faint()

Faint (decreased intensity). Not widely supported.

font_1()

Sets alternative font 1.

font_2()

Sets alternative font 2.

font_3()

Sets alternative font 3.

font_4()

Sets alternative font 4.

font_5()

Sets alternative font 5.

font_6()

Sets alternative font 6.

font_7()

Sets alternative font 7.

font_8()

Sets alternative font 8.

font_9()

Sets alternative font 9.

format(chardata, emit? \\ enabled?())

Formats a chardata-like argument by converting named ANSI sequences into actual ANSI codes.

format_fragment(chardata, emit? \\ enabled?())

Formats a chardata-like argument by converting named ANSI sequences into actual ANSI codes.

framed()

Framed.

green()

Sets foreground color to green.

green_background()

Sets background color to green.

home()

Sends cursor home.

inverse()

Image: negative. Swap foreground and background.

inverse_off()

Image: positive. Normal foreground and background.

italic()

Italic: on. Not widely supported. Sometimes treated as inverse.

light_black()

Sets foreground color to light black.

light_black_background()

Sets background color to light black.

light_blue()

Sets foreground color to light blue.

light_blue_background()

Sets background color to light blue.

light_cyan()

Sets foreground color to light cyan.

light_cyan_background()

Sets background color to light cyan.

light_green()

Sets foreground color to light green.

light_green_background()

Sets background color to light green.

light_magenta()

Sets foreground color to light magenta.

light_magenta_background()

Sets background color to light magenta.

light_red()

Sets foreground color to light red.

light_red_background()

Sets background color to light red.

light_white()

Sets foreground color to light white.

light_white_background()

Sets background color to light white.

light_yellow()

Sets foreground color to light yellow.

light_yellow_background()

Sets background color to light yellow.

magenta()

Sets foreground color to magenta.

magenta_background()

Sets background color to magenta.

no_underline()

Underline: none.

normal()

Normal color or intensity.

not_framed_encircled()

Not framed or encircled.

not_italic()

Not italic.

not_overlined()

Not overlined.

overlined()

Overlined.

primary_font()

Sets primary (default) font.

red()

Sets foreground color to red.

red_background()

Sets background color to red.

reset()

Resets all attributes.

reverse()

Image: negative. Swap foreground and background.

reverse_off()

Image: positive. Normal foreground and background.

underline()

Underline: single.

white()

Sets foreground color to white.

white_background()

Sets background color to white.

yellow()

Sets foreground color to yellow.

yellow_background()

Sets background color to yellow.

Link to this section Types

Link to this type

ansicode()

View Source 
@type ansicode() :: atom()
Link to this type

ansidata()

View Source 
@type ansidata() :: ansilist() | ansicode() | binary()
Link to this type

ansilist()

View Source 
@type ansilist() ::
  maybe_improper_list(
    char() | ansicode() | binary() | ansilist(),
    binary() | ansicode() | []
  )

Link to this section Functions

Link to this function

black()

View Source

Sets foreground color to black.

Link to this function

black_background()

View Source

Sets background color to black.

Link to this function

blue()

View Source

Sets foreground color to blue.

Link to this function

blue_background()

View Source

Sets background color to blue.

Link to this function

bright()

View Source

Bright (increased intensity) or bold.

Link to this function

clear()

View Source

Clears screen.

Link to this function

clear_line()

View Source

Clears line.

Link to this function

color(code)

View Source 
@spec color(0..255) :: String.t()

Sets foreground color.

Link to this function

color(r, g, b)

View Source 
@spec color(0..5, 0..5, 0..5) :: String.t()

Sets the foreground color from individual RGB values.

Valid values for each color are in the range 0 to 5.

Link to this function

color_background(code)

View Source 
@spec color_background(0..255) :: String.t()

Sets background color.

Link to this function

color_background(r, g, b)

View Source 
@spec color_background(0..5, 0..5, 0..5) :: String.t()

Sets the background color from individual RGB values.

Valid values for each color are in the range 0 to 5.

Link to this function

conceal()

View Source

Conceal. Not widely supported.

Link to this function

crossed_out()

View Source

Crossed-out. Characters legible, but marked for deletion. Not widely supported.

Link to this function

cursor(line, column)

View Source 
@spec cursor(non_neg_integer(), non_neg_integer()) :: String.t()

Sends cursor to the absolute position specified by line and column.

Line 0 and column 0 would mean the top left corner.

Link to this function

cursor_down(lines \\ 1)

View Source 
@spec cursor_down(pos_integer()) :: String.t()

Sends cursor lines down.

Link to this function

cursor_left(columns \\ 1)

View Source 
@spec cursor_left(pos_integer()) :: String.t()

Sends cursor columns to the left.

Link to this function

cursor_right(columns \\ 1)

View Source 
@spec cursor_right(pos_integer()) :: String.t()

Sends cursor columns to the right.

Link to this function

cursor_up(lines \\ 1)

View Source 
@spec cursor_up(pos_integer()) :: String.t()

Sends cursor lines up.

Link to this function

cyan()

View Source

Sets foreground color to cyan.

Link to this function

cyan_background()

View Source

Sets background color to cyan.

Link to this function

default_background()

View Source

Default background color.

Link to this function

default_color()

View Source

Default text color.

Link to this function

enabled?()

View Source 
@spec enabled?() :: boolean()

Checks if ANSI coloring is supported and enabled on this machine.

This function simply reads the configuration value for :ansi_enabled in the :elixir application. The value is by default false unless Elixir can detect during startup that both stdout and stderr are terminals.

Link to this function

encircled()

View Source

Encircled.

Link to this function

faint()

View Source

Faint (decreased intensity). Not widely supported.

Link to this function

font_1()

View Source

Sets alternative font 1.

Link to this function

font_2()

View Source

Sets alternative font 2.

Link to this function

font_3()

View Source

Sets alternative font 3.

Link to this function

font_4()

View Source

Sets alternative font 4.

Link to this function

font_5()

View Source

Sets alternative font 5.

Link to this function

font_6()

View Source

Sets alternative font 6.

Link to this function

font_7()

View Source

Sets alternative font 7.

Link to this function

font_8()

View Source

Sets alternative font 8.

Link to this function

font_9()

View Source

Sets alternative font 9.

Link to this function

format(chardata, emit? \\ enabled?())

View Source

Formats a chardata-like argument by converting named ANSI sequences into actual ANSI codes.

The named sequences are represented by atoms.

It will also append an IO.ANSI.reset/0 to the chardata when a conversion is performed. If you don't want this behaviour, use format_fragment/2.

An optional boolean parameter can be passed to enable or disable emitting actual ANSI codes. When false, no ANSI codes will be emitted. By default checks if ANSI is enabled using the enabled?/0 function.

Examples 

iex> IO.ANSI.format(["Hello, ", :red, :bright, "world!"], true)
[[[[[[], "Hello, "] | "\e[31m"] | "\e[1m"], "world!"] | "\e[0m"]
Link to this function

format_fragment(chardata, emit? \\ enabled?())

View Source

Formats a chardata-like argument by converting named ANSI sequences into actual ANSI codes.

The named sequences are represented by atoms.

An optional boolean parameter can be passed to enable or disable emitting actual ANSI codes. When false, no ANSI codes will be emitted. By default checks if ANSI is enabled using the enabled?/0 function.

Examples 

iex> IO.ANSI.format_fragment([:bright, 'Word'], true)
[[[[[[] | "\e[1m"], 87], 111], 114], 100]
Link to this function

framed()

View Source

Framed.

Link to this function

green()

View Source

Sets foreground color to green.

Link to this function

green_background()

View Source

Sets background color to green.

Link to this function

home()

View Source

Sends cursor home.

Link to this function

inverse()

View Source

Image: negative. Swap foreground and background.

Link to this function

inverse_off()

View Source

Image: positive. Normal foreground and background.

Link to this function

italic()

View Source

Italic: on. Not widely supported. Sometimes treated as inverse.

Link to this function

light_black()

View Source

Sets foreground color to light black.

Link to this function

light_black_background()

View Source

Sets background color to light black.

Link to this function

light_blue()

View Source

Sets foreground color to light blue.

Link to this function

light_blue_background()

View Source

Sets background color to light blue.

Link to this function

light_cyan()

View Source

Sets foreground color to light cyan.

Link to this function

light_cyan_background()

View Source

Sets background color to light cyan.

Link to this function

light_green()

View Source

Sets foreground color to light green.

Link to this function

light_green_background()

View Source

Sets background color to light green.

Link to this function

light_magenta()

View Source

Sets foreground color to light magenta.

Link to this function

light_magenta_background()

View Source

Sets background color to light magenta.

Link to this function

light_red()

View Source

Sets foreground color to light red.

Link to this function

light_red_background()

View Source

Sets background color to light red.

Link to this function

light_white()

View Source

Sets foreground color to light white.

Link to this function

light_white_background()

View Source

Sets background color to light white.

Link to this function

light_yellow()

View Source

Sets foreground color to light yellow.

Link to this function

light_yellow_background()

View Source

Sets background color to light yellow.

Link to this function

magenta()

View Source

Sets foreground color to magenta.

Link to this function

magenta_background()

View Source

Sets background color to magenta.

Link to this function

no_underline()

View Source

Underline: none.

Link to this function

normal()

View Source

Normal color or intensity.

Link to this function

not_framed_encircled()

View Source

Not framed or encircled.

Link to this function

not_italic()

View Source

Not italic.

Link to this function

not_overlined()

View Source

Not overlined.

Link to this function

overlined()

View Source

Overlined.

Link to this function

primary_font()

View Source

Sets primary (default) font.

Link to this function

red()

View Source

Sets foreground color to red.

Link to this function

red_background()

View Source

Sets background color to red.

Link to this function

reset()

View Source

Resets all attributes.

Link to this function

reverse()

View Source

Image: negative. Swap foreground and background.

Link to this function

reverse_off()

View Source

Image: positive. Normal foreground and background.

Link to this function

underline()

View Source

Underline: single.

Link to this function

white()

View Source

Sets foreground color to white.

Link to this function

white_background()

View Source

Sets background color to white.

Link to this function

yellow()

View Source

Sets foreground color to yellow.

Link to this function

yellow_background()

View Source

Sets background color to yellow.