View Source Escape (escape v0.1.0)

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

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

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.

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

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

Functions

@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"] | ""]
Link to this function

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

View Source
@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 append an IO.ANSI.reset/0 when true.

  • :emit enables or disables emitting ANSI codes.

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"] | ""]
Link to this function

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

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

Link to this function

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

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