Escape (escape v0.3.0)

View Source

Functionality to render ANSI escape sequences.

This module is quite similar to the Elixir module IO.ANSI. For more info about ANSI escape sequences, see the IO.ANSI documentation.

For example, the function IO.ANSI.format/1 and Escape.format/1 working in the same way.

iex> iodata = IO.ANSI.format([:green, "hello"])
[[[[] | ""], "hello"] | ""]
iex> iodata == Escape.format([:green, "hello"])
true

The Escape module adds the option :theme to Escape.format/2.

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

In the theme are ANSI escape sequeneces allowed.

iex> Escape.format([:say, "hello"], theme: %{
...>   orange: IO.ANSI.color(178),
...>   say: :orange
...> })
[[[[] | ""], "hello"] | ""]

The theme can also contain further formats.

iex> theme = %{
...>   orange: IO.ANSI.color(5, 3, 0),
...>   gray_background: IO.ANSI.color_background(59),
...>   say: [:orange, :gray_background],
...>   blank: " "
...> }
iex> Escape.format([:say, :blank, "hello", :blank], theme: theme)
[[[[[[], [[] | ""] | ""] | " "], "hello"] | " "] | ""]
iex> Escape.format([:say, :blank, "hello", :blank], theme: theme, emit: false)
[[], "hello"]

See Escape.format/2 for more info.

Summary

Functions

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

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

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

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

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

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

Formats a named ANSI sequences into an ANSI sequence.

Returns a list of all available named ANSI sequences.

Writes ansidata to a device.

Types

ansicode()

@type ansicode() :: atom()

ansidata()

@type ansidata() :: ansilist() | ansicode() | binary()

ansilist()

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

Functions

color_doc(doc, color_key, opts \\ [])

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

colorizer(opts)

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

format(ansidata, opts \\ [emit: ANSI.enabled?(), reset: true])

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

formatter(opts)

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

length(string_or_ansidata)

@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

puts(ansidata, opts \\ [device: :stdio])

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

sequence(ansicode)

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

sequences()

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

write(ansidata, opts \\ [device: :stdio])

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