@spec color_doc(Inspect.Algebra.t(), ansicode(), keyword()) :: Inspect.Algebra.t()

Colors a Inspect.Algebra document if the color_key has a color in the theme.

This function is similar to Inspect.Algebra.color/3 but has a different options argument.

Options

• :theme a map of ANSI codes. The searching in the theme performs a deep search.

• :emit enables or disables emitting ANSI codes. Defaults to IO.ANSI.enabled?/0.

@spec colorizer(keyword()) :: (String.t(), ansicode() -> String.t())

Returns a function that accepts a string and a named sequence and returns iodata with the applied format.

Accepts the same options as format/2.

Examples

iex> colorizer = Escape.colorizer(theme: %{say: :green})
iex> colorizer.("hello", :say)
[[[[] | ""], "hello"] | ""]

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

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

The named sequences are represented by atoms. The named sequences can be extended by a map for the option :theme.

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 the option reset?: false.

The option :emit can be passed to enable or disable emitting ANSI codes. When false, no ANSI codes will be emitted. This option defaults to the return value of IO.ANSI.enabled?/0.

Options

• :theme a map that adds ANSI codes usable in the chardata-like argument. The searching in the theme performs a deep search.

• :reset appends an IO.ANSI.reset/0 when true. Defaults to true.

• :emit enables or disables emitting ANSI codes. Defaults to IO.ANSI.enabled?/0.

Examples

iex> theme = %{
...>   gainsboro: ANSI.color(4, 4, 4),
...>   orange: ANSI.color(5, 3, 0),
...>   aquamarine: ANSI.color(2, 5, 4),
...>   error: :red,
...>   debug: :orange,
...>   info: :gainsboro
...> }
iex> Escape.format([:error, "error"], theme: theme)
[[[[] | ""], "error"] | ""]
iex> Escape.format([:info, "info"], theme: theme)
[[[[] | ""], "info"] | ""]
iex> Escape.format([:info, "info"], theme: theme, reset: false)
[[[] | ""], "info"]
iex> Escape.format([:info, "info"], theme: theme, emit: false)
[[], "info"]

@spec formatter(keyword()) :: (ansidata() -> String.t())

Returns a function that accepts a chardata-like argument and applies Escape.format/2 with the argument and the given opts.

Examples

iex> formatter = Escape.formatter(theme: %{say: :green})
iex> formatter.([:say, "hello"])
[[[[] | ""], "hello"] | ""]

@spec length(String.t() | ansidata()) :: non_neg_integer()

Returns the length of a string or ansidata without ANSI escape sequences.

Examples

iex> String.length("Hello, world!")
13
iex> [:green, "Hello", :reset, ", ", :blue, "world!"]
...> |> Escape.format()
...> |> Escape.length()
13
iex> [:green, "Hello", :reset, ", ", :blue, "world!"]
...> |> Escape.format()
...> |> IO.iodata_to_binary()
...> |> Escape.length()
13

@spec puts(
  ansidata(),
  keyword()
) :: :ok

Writes ansidata to a device, similar to write/2, but adds a newline at the end.

The device is passed to the function with the option :device in the opts and defaults to standard output.

The function also accepts the same options as Escape.format/2.

@spec sequence(ansicode()) :: String.t()

Formats a named ANSI sequences into an ANSI sequence.

The named sequences are represented by atoms.

Examples

iex> Escape.sequence(:reverse)
""

@spec sequences() :: [ansicode()]

Returns a list of all available named ANSI sequences.

Examples

iex> Escape.sequences()
[:black, :black_background, :blink_off, :blink_rapid, :blink_slow, :blue,
:blue_background, :bright, :conceal, :crossed_out, :cyan, :cyan_background,
:default_background, :default_color, :encircled, :faint, :font_1, :font_2,
:font_3, :font_4, :font_5, :font_6, :font_7, :font_8, :font_9, :framed, :green,
:green_background, :home, :inverse, :inverse_off, :italic, :light_black,
:light_black_background, :light_blue, :light_blue_background, :light_cyan,
:light_cyan_background, :light_green, :light_green_background, :light_magenta,
:light_magenta_background, :light_red, :light_red_background, :light_white,
:light_white_background, :light_yellow, :light_yellow_background, :magenta,
:magenta_background, :no_underline, :normal, :not_framed_encircled,
:not_italic, :not_overlined, :overlined, :primary_font, :red, :red_background,
:reset, :reverse, :reverse_off, :underline, :white, :white_background, :yellow,
:yellow_background]

@spec split_at(String.t(), non_neg_integer()) :: {String.t(), String.t()}

Splits a string into two parts at the specified offset, respecting ANSI escape sequences.

Examples

iex> string = [:red, "red", :green, "green"]
...>   |> Escape.format(reset: false)
...>   |> IO.iodata_to_binary()
iex> Escape.split_at(string, 3)
{"\e[31mred", "\e[32mgreen"}
iex> Escape.split_at(string, 1)
{"\e[31mr", "ed\e[32mgreen"}

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

Returns the given string stripped of all escape sequences.

Examples

iex> [:green, "Hello, ", :green, "world!"]
...> |> Escape.format(reset: false)
...> |> IO.iodata_to_binary()
...> |> Escape.strip_sequences()
"Hello, world!"

@spec write(
  ansidata(),
  keyword()
) :: :ok

Writes ansidata to a device.

The device is passed to the function with the option :device in the opts and defaults to standard output.

The function also accepts the same options as Escape.format/2.