Escape (escape v0.4.0)
View SourceFunctionality 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"])
[[[[] | "[32m"], "hello"] | "[0m"]
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})
[[[[] | "[32m"], "hello"] | "[0m"]
In the theme are ANSI escape sequeneces allowed.
iex> Escape.format([:say, "hello"], theme: %{
...> orange: IO.ANSI.color(178),
...> say: :orange
...> })
[[[[] | "[38;5;178m"], "hello"] | "[0m"]
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)
[[[[[[], [[] | "[38;5;214m"] | "[48;5;59m"] | " "], "hello"] | " "] | "[0m"]
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.
Splits a string into two parts at the specified offset, respecting ANSI escape sequences.
Returns the given string
stripped of all escape sequences.
Writes ansidata
to a device.
Types
Functions
@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 toIO.ANSI.enabled?/0
.
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)
[[[[] | "[32m"], "hello"] | "[0m"]
@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 anIO.ANSI.reset/0
when true. Defaults totrue
.:emit
enables or disables emitting ANSI codes. Defaults toIO.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)
[[[[] | "[31m"], "error"] | "[0m"]
iex> Escape.format([:info, "info"], theme: theme)
[[[[] | "[38;5;188m"], "info"] | "[0m"]
iex> Escape.format([:info, "info"], theme: theme, reset: false)
[[[] | "[38;5;188m"], "info"]
iex> Escape.format([:info, "info"], theme: theme, emit: false)
[[], "info"]
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"])
[[[[] | "[32m"], "hello"] | "[0m"]
@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
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
.
Formats a named ANSI sequences into an ANSI sequence.
The named sequences are represented by atoms.
Examples
iex> Escape.sequence(:reverse)
"[7m"
@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"}
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!"
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
.