IO.ANSI — Elixir v1.16.3

Search documentation of Elixir

# View Source IO.ANSI (Elixir v1.16.3)

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.

# 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(ansidata, emit? \\ enabled?())

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

format_fragment(ansidata, 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.

syntax_colors()

Syntax colors to be used by `Inspect`.

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.

# 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() | []
      )

# Functions

Link to this function

# black()

View Source

    @spec black() :: String.t()

Sets foreground color to black.

Link to this function

# black_background()

View Source

    @spec black_background() :: String.t()

Sets background color to black.

Link to this function

# blink_off()

View Source

    @spec blink_off() :: String.t()

Blink: off.

Link to this function

# blink_rapid()

View Source

    @spec blink_rapid() :: String.t()

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

Link to this function

# blink_slow()

View Source

    @spec blink_slow() :: String.t()

Blink: slow. Less than 150 per minute.

Link to this function

# blue()

View Source

    @spec blue() :: String.t()

Sets foreground color to blue.

Link to this function

# blue_background()

View Source

    @spec blue_background() :: String.t()

Sets background color to blue.

Link to this function

# bright()

View Source

    @spec bright() :: String.t()

Bright (increased intensity) or bold.

Link to this function

# clear()

View Source

    @spec clear() :: String.t()

Clears screen.

Link to this function

# clear_line()

View Source

    @spec clear_line() :: String.t()

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

    @spec conceal() :: String.t()

Conceal. Not widely supported.

Link to this function

# crossed_out()

View Source

    @spec crossed_out() :: String.t()

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

    @spec cyan() :: String.t()

Sets foreground color to cyan.

Link to this function

# cyan_background()

View Source

    @spec cyan_background() :: String.t()

Sets background color to cyan.

Link to this function

# default_background()

View Source

    @spec default_background() :: String.t()

Default background color.

Link to this function

# default_color()

View Source

    @spec default_color() :: String.t()

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

    @spec encircled() :: String.t()

Encircled.

Link to this function

# faint()

View Source

    @spec faint() :: String.t()

Faint (decreased intensity). Not widely supported.

Link to this function

# font_1()

View Source

    @spec font_1() :: String.t()

Sets alternative font 1.

Link to this function

# font_2()

View Source

    @spec font_2() :: String.t()

Sets alternative font 2.

Link to this function

# font_3()

View Source

    @spec font_3() :: String.t()

Sets alternative font 3.

Link to this function

# font_4()

View Source

    @spec font_4() :: String.t()

Sets alternative font 4.

Link to this function

# font_5()

View Source

    @spec font_5() :: String.t()

Sets alternative font 5.

Link to this function

# font_6()

View Source

    @spec font_6() :: String.t()

Sets alternative font 6.

Link to this function

# font_7()

View Source

    @spec font_7() :: String.t()

Sets alternative font 7.

Link to this function

# font_8()

View Source

    @spec font_8() :: String.t()

Sets alternative font 8.

Link to this function

# font_9()

View Source

    @spec font_9() :: String.t()

Sets alternative font 9.

Link to this function

# format(ansidata, emit? \\ enabled?())

View Source

    @spec format(ansidata(), boolean()) :: IO.chardata()

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.

An `ArgumentError` will be raised if an invalid ANSI code is provided.

## Examples

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

Link to this function

# format_fragment(ansidata, emit? \\ enabled?())

View Source

    @spec format_fragment(ansidata(), boolean()) :: IO.chardata()

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

    @spec framed() :: String.t()

Framed.

Link to this function

# green()

View Source

    @spec green() :: String.t()

Sets foreground color to green.

Link to this function

# green_background()

View Source

    @spec green_background() :: String.t()

Sets background color to green.

Link to this function

# home()

View Source

    @spec home() :: String.t()

Sends cursor home.

Link to this function

# inverse()

View Source

    @spec inverse() :: String.t()

Image: negative. Swap foreground and background.

Link to this function

# inverse_off()

View Source

    @spec inverse_off() :: String.t()

Image: positive. Normal foreground and background.

Link to this function

# italic()

View Source

    @spec italic() :: String.t()

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

Link to this function

# light_black()

View Source

    @spec light_black() :: String.t()

Sets foreground color to light black.

Link to this function

# light_black_background()

View Source

    @spec light_black_background() :: String.t()

Sets background color to light black.

Link to this function

# light_blue()

View Source

    @spec light_blue() :: String.t()

Sets foreground color to light blue.

Link to this function

# light_blue_background()

View Source

    @spec light_blue_background() :: String.t()

Sets background color to light blue.

Link to this function

# light_cyan()

View Source

    @spec light_cyan() :: String.t()

Sets foreground color to light cyan.

Link to this function

# light_cyan_background()

View Source

    @spec light_cyan_background() :: String.t()

Sets background color to light cyan.

Link to this function

# light_green()

View Source

    @spec light_green() :: String.t()

Sets foreground color to light green.

Link to this function

# light_green_background()

View Source

    @spec light_green_background() :: String.t()

Sets background color to light green.

Link to this function

# light_magenta()

View Source

    @spec light_magenta() :: String.t()

Sets foreground color to light magenta.

Link to this function

# light_magenta_background()

View Source

    @spec light_magenta_background() :: String.t()

Sets background color to light magenta.

Link to this function

# light_red()

View Source

    @spec light_red() :: String.t()

Sets foreground color to light red.

Link to this function

# light_red_background()

View Source

    @spec light_red_background() :: String.t()

Sets background color to light red.

Link to this function

# light_white()

View Source

    @spec light_white() :: String.t()

Sets foreground color to light white.

Link to this function

# light_white_background()

View Source

    @spec light_white_background() :: String.t()

Sets background color to light white.

Link to this function

# light_yellow()

View Source

    @spec light_yellow() :: String.t()

Sets foreground color to light yellow.

Link to this function

# light_yellow_background()

View Source

    @spec light_yellow_background() :: String.t()

Sets background color to light yellow.

Link to this function

# magenta()

View Source

    @spec magenta() :: String.t()

Sets foreground color to magenta.

Link to this function

# magenta_background()

View Source

    @spec magenta_background() :: String.t()

Sets background color to magenta.

Link to this function

# no_underline()

View Source

    @spec no_underline() :: String.t()

Underline: none.

Link to this function

# normal()

View Source

    @spec normal() :: String.t()

Normal color or intensity.

Link to this function

# not_framed_encircled()

View Source

    @spec not_framed_encircled() :: String.t()

Not framed or encircled.

Link to this function

# not_italic()

View Source

    @spec not_italic() :: String.t()

Not italic.

Link to this function

# not_overlined()

View Source

    @spec not_overlined() :: String.t()

Not overlined.

Link to this function

# overlined()

View Source

    @spec overlined() :: String.t()

Overlined.

Link to this function

# primary_font()

View Source

    @spec primary_font() :: String.t()

Sets primary (default) font.

Link to this function

# red()

View Source

    @spec red() :: String.t()

Sets foreground color to red.

Link to this function

# red_background()

View Source

    @spec red_background() :: String.t()

Sets background color to red.

Link to this function

# reset()

View Source

    @spec reset() :: String.t()

Resets all attributes.

Link to this function

# reverse()

View Source

    @spec reverse() :: String.t()

Image: negative. Swap foreground and background.

Link to this function

# reverse_off()

View Source

    @spec reverse_off() :: String.t()

Image: positive. Normal foreground and background.

Link to this function

# syntax_colors()

View Source (since 1.14.0)

    @spec syntax_colors() :: Keyword.t(ansidata())

Syntax colors to be used by `Inspect`.

Those colors are used throughout Elixir's standard library, such as `dbg/2` and `IEx`.

The colors can be changed by setting the `:ansi_syntax_colors` in the `:elixir` application configuration. Configuration for most built-in data types are supported: `:atom`, `:binary`, `:boolean`, `:charlist`, `:list`, `:map`, `:nil`, `:number`, `:string`, and `:tuple`. The default is:

    [
      atom: :cyan
      boolean: :magenta,
      charlist: :yellow,
      nil: :magenta,
      number: :yellow,
      string: :green
    ]

Link to this function

# underline()

View Source

    @spec underline() :: String.t()

Underline: single.

Link to this function

# white()

View Source

    @spec white() :: String.t()

Sets foreground color to white.

Link to this function

# white_background()

View Source

    @spec white_background() :: String.t()

Sets background color to white.

Link to this function

# yellow()

View Source

    @spec yellow() :: String.t()

Sets foreground color to yellow.

Link to this function

# yellow_background()

View Source

    @spec yellow_background() :: String.t()

Sets background color to yellow.