ANSI text color and style string builder for Lua.
Works with Lua 5.1, 5.2, 5.3, 5.4, 5.5, and LuaJIT.
luarocks install ansifylocal ansify = require "ansify"
local style = ansify.style
local fg = ansify.foregrounds
local bg = ansify.backgrounds
local mods = ansify.modifiers
print(style({ fg.green }, "success"))
print(style({ "bold", "blue" }, "hello"))
print(style({ bg.bright_red }, " alert "))
print(style({ "bold", "white", "on_red" }, " fatal "))
print(style({ mods.underline, fg.bright_cyan }, "https://example.com"))
print(style({ mods.bold, fg.yellow, bg.blue }, " warning "))
print(style({ "underline", "magenta" }, "label"))
print(fg.green(mods.bold("done")))
print(ansify.format("{bold}{red}ERROR{normal} config missing"))
print(ansify.prepend(style({ "bold", "red" }, "config missing"), "ERROR: "))Foreground colors set the text color.
black, red, green, yellow, blue, magenta, cyan, white,
bright_black, bright_red, bright_green, bright_yellow, bright_blue,
bright_magenta, bright_cyan, bright_white
Foreground values are callable and can also be converted to raw ANSI escape
sequences with tostring(...).
Examples:
print(ansify.style({ ansify.foregrounds.red }, "error"))
print(ansify.style({ ansify.foregrounds.bright_red }, "alert"))
print(ansify.style({ ansify.foregrounds.bright_blue }, "bright blue"))
print(ansify.foregrounds.green("success"))
print(tostring(ansify.foregrounds.red))Background colors set the color behind the text.
on_black, on_red, on_green, on_yellow, on_blue, on_magenta,
on_cyan, on_white, on_bright_black, on_bright_red, on_bright_green,
on_bright_yellow, on_bright_blue, on_bright_magenta, on_bright_cyan,
on_bright_white
Background values are callable and can also be converted to raw ANSI escape
sequences with tostring(...).
Examples:
print(ansify.style({ ansify.backgrounds.blue }, "panel"))
print(ansify.style({ ansify.backgrounds.bright_blue }, "panel"))
print(ansify.backgrounds.bright_blue(" panel "))Modifiers change how text is displayed without changing its foreground or background color.
bold, dim, italic, underline, inverse, strikethrough
Modifier values are callable and can also be composed manually with string concatenation.
Examples:
print(ansify.style({ "underline" }, "underline"))
print(ansify.modifiers.underline("path/to/config.lua"))
print(ansify.modifiers.bold .. ansify.foregrounds.red .. "error" .. ansify.modifiers.reset)
print(ansify.foregrounds.red .. "error" .. ansify.modifiers.reset)ansify.modifiers.reset is also exported as a low-level ANSI reset sequence for
manual composition, but reset is not accepted by ansify.style(...).
| Function | Description |
|---|---|
style |
Apply one or more ANSI styles to text. |
format |
Resolve inline style tags such as {bold} and {red}. |
append |
Add text before a styled string's trailing reset. |
prepend |
Add text after a styled string's opening ANSI sequence. |
slice |
Extract a visible substring without breaking ANSI styling. |
has_ansi |
Check whether a string contains ANSI SGR sequences. |
words |
Split visible words while preserving styling on each piece. |
lines |
Split lines while keeping ANSI styling renderable. |
wrap |
Wrap styled text to a visible width. |
len |
Return visible string length with ANSI removed. |
align |
Align styled text within a visible width. |
truncate |
Trim styled text to a visible width safely. |
strip |
Remove ANSI SGR escape sequences. |
escape |
Escape control characters into printable sequences. |
Build a styled string from style names or exported style objects and text.
print(ansify.style({ "red" }, "error"))
print(ansify.style({ "underline", "blue" }, "label"))
print(ansify.style({ ansify.modifiers.bold, ansify.foregrounds.cyan }, "info"))
print(ansify.style({ "bright_red" }, "alert"))
print(ansify.style({ "on_bright_blue" }, "panel"))Notes:
- modifiers are emitted in a stable order
- duplicate modifiers are ignored
- when multiple foreground colors are provided, the last one wins
- when multiple background colors are provided, the last one wins
- bright colors use explicit names like
bright_redandon_bright_blue - exported values in
foregrounds,backgrounds, andmodifiersare callable style objects tostring(value)returns the raw ANSI escape sequencevalue("text")wraps text with that ANSI sequence- string concatenation with
..uses the ANSI escape string value ansify.modifiers.resetis available for manual composition, butresetis not a valid style name
Render inline style tags into ANSI text.
print(ansify.format("{bold}{red}ERROR{normal} config missing"))
print(ansify.format("{underline}config.lua{normal}"))
print(ansify.format("{bold}{red}alert{normal}"))Tags use the same style names accepted by ansify.style(...), plus normal to
clear the active formatting. Modifiers and colors stay active until changed or
cleared.
Append text while preserving the existing outer ANSI style when possible.
local label = ansify.style({ "bold", "red" }, "ERROR")
print(ansify.append(label, ": config missing"))Prepend text while preserving the existing outer ANSI style when possible.
local message = ansify.style({ "bold", "red" }, "config missing")
print(ansify.prepend(message, "ERROR: "))Extract a visible substring while preserving ANSI styling.
local text = ansify.style({ "red" }, "fatal error in config loader")
print(ansify.slice(text, 7, 11))Check whether a string contains ANSI escape sequences.
print(ansify.has_ansi(ansify.style({ "red" }, "error")))
print(ansify.has_ansi("plain"))Split text into words while preserving ANSI styling on each returned word.
local words = ansify.words(ansify.style({ "red" }, "build command failed"))
print(words[1], words[2], words[3])Split text into lines while preserving ANSI styling on each returned line.
local lines = ansify.lines(ansify.style({ "red" }, "one\ntwo"))
print(lines[1], lines[2])Wrap text to a visible width while preserving ANSI styling on wrapped lines.
local option = ansify.align(
local option = ansify.align(ansify.style({ "bold", "cyan" }, " --output <file>"), 22, "left")
local description = "Write the rendered deployment report to a file instead of standard output."
print(ansify.wrap(option .. description, 60))Count visible characters after ANSI escape sequences are removed.
print(ansify.len(ansify.style({ "red" }, "error")))Align a string using visible width instead of raw byte length.
print(ansify.align(ansify.style({ "red" }, "ok"), 5, "left"))
print(ansify.align(ansify.style({ "red" }, "ok"), 5, "right"))
print(ansify.align(ansify.style({ "red" }, "ok"), 5, "center"))ansify.truncate(text, width)Trim a string to a visible width while preserving ANSI styling.
print(ansify.truncate(ansify.style({ "red" }, "error"), 3))Remove ANSI escape sequences from a string.
local styled = ansify.style({ "red" }, "error")
print(ansify.strip(styled))Escape control characters so ANSI output is readable in plain text.
print(ansify.escape(ansify.style({ "red" }, "error")))