ansify

ANSI text color and style string builder for Lua.

Works with Lua 5.1, 5.2, 5.3, 5.4, 5.5, and LuaJIT.

Install

luarocks install ansify

Usage

localansify=require"ansify"localstyle=ansify.stylelocalfg=ansify.foregroundslocalbg=ansify.backgroundslocalmods=ansify.modifiersprint(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: "))

Api

Foreground Colors

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

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

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(...).

Functions

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.

ansify.style(style_or_styles, text)

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_red and on_bright_blue
• exported values in foregrounds, backgrounds, and modifiers are callable style objects
• tostring(value) returns the raw ANSI escape sequence
• value("text") wraps text with that ANSI sequence
• string concatenation with .. uses the ANSI escape string value
• ansify.modifiers.reset is available for manual composition, but reset is not a valid style name

ansify.format(text)

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.

ansify.append(text, suffix)

Append text while preserving the existing outer ANSI style when possible.

locallabel=ansify.style({ "bold", "red" }, "ERROR")
print(ansify.append(label, ": config missing"))

ansify.prepend(text, prefix)

Prepend text while preserving the existing outer ANSI style when possible.

localmessage=ansify.style({ "bold", "red" }, "config missing")
print(ansify.prepend(message, "ERROR: "))

ansify.slice(text, start, finish)

Extract a visible substring while preserving ANSI styling.

localtext=ansify.style({ "red" }, "fatal error in config loader")
print(ansify.slice(text, 7, 11))

ansify.has_ansi(text)

Check whether a string contains ANSI escape sequences.

print(ansify.has_ansi(ansify.style({ "red" }, "error")))
print(ansify.has_ansi("plain"))

ansify.words(text)

Split text into words while preserving ANSI styling on each returned word.

localwords=ansify.words(ansify.style({ "red" }, "build command failed"))
print(words[1], words[2], words[3])

ansify.lines(text)

Split text into lines while preserving ANSI styling on each returned line.

locallines=ansify.lines(ansify.style({ "red" }, "one\ntwo"))
print(lines[1], lines[2])

ansify.wrap(text, width)

Wrap text to a visible width while preserving ANSI styling on wrapped lines.

localoption=ansify.align(
localoption=ansify.align(ansify.style({ "bold", "cyan" }, " --output <file>"), 22, "left")
localdescription="Write the rendered deployment report to a file instead of standard output."print(ansify.wrap(option..description, 60))

ansify.len(text)

Count visible characters after ANSI escape sequences are removed.

print(ansify.len(ansify.style({ "red" }, "error")))

ansify.align(text, width, direction)

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)

ansify.truncate(text, width)

Trim a string to a visible width while preserving ANSI styling.

print(ansify.truncate(ansify.style({ "red" }, "error"), 3))

ansify.strip(text)

Remove ANSI escape sequences from a string.

localstyled=ansify.style({ "red" }, "error")
print(ansify.strip(styled))

ansify.escape(value)

Escape control characters so ANSI output is readable in plain text.

print(ansify.escape(ansify.style({ "red" }, "error")))