---@meta ansify

---@alias ansify.styleName

---| ansify.modifierName

---| ansify.foregroundName

---| ansify.backgroundName

---@alias ansify.modifierName

---| 'bold'

---| 'dim'

---| 'italic'

---| 'underline'

---| 'inverse'

---| 'strikethrough'

---@alias ansify.foregroundName

---| 'red'

---| 'green'

---| 'blue'

---| 'cyan'

---| 'magenta'

---| 'yellow'

---| 'black'

---| 'white'

---| 'bright_red'

---| 'bright_green'

---| 'bright_blue'

---| 'bright_cyan'

---| 'bright_magenta'

---| 'bright_yellow'

---| 'bright_black'

---| 'bright_white'

---@alias ansify.backgroundName

---| 'on_red'

---| 'on_green'

---| 'on_blue'

---| 'on_cyan'

---| 'on_magenta'

---| 'on_yellow'

---| 'on_black'

---| 'on_white'

---| 'on_bright_red'

---| 'on_bright_green'

---| 'on_bright_blue'

---| 'on_bright_cyan'

---| 'on_bright_magenta'

---| 'on_bright_yellow'

---| 'on_bright_black'

---| 'on_bright_white'

---@class ansify.Style<T1,T2,T3>

---@field name T1

---@field code T2

---@field value T3

---@field category 'modifier'|'foreground'|'background'

---@class ansify.modifiers

---@field bold ansify.Style<"bold" , 1, "\27[1m">

---@field dim ansify.Style<"dim" , 2, "\27[2m">

---@field italic ansify.Style<"italic" , 3, "\27[3m">

---@field underline ansify.Style<"underline" , 4, "\27[4m">

---@field inverse ansify.Style<"inverse" , 7, "\27[7m">

---@field strikethrough ansify.Style<"strikethrough", 9, "\27[9m">

---@field reset ansify.Style<"reset" , 0, "\27[0m">

local modifiers = {}

---@class ansify.foregrounds

---@field red ansify.Style<"red" , 31, "\27[31m">

---@field green ansify.Style<"green" , 32, "\27[32m">

---@field blue ansify.Style<"blue" , 34, "\27[34m">

---@field cyan ansify.Style<"cyan" , 36, "\27[36m">

---@field magenta ansify.Style<"magenta" , 35, "\27[35m">

---@field yellow ansify.Style<"yellow" , 33, "\27[33m">

---@field black ansify.Style<"black" , 30, "\27[30m">

---@field white ansify.Style<"white" , 37, "\27[37m">

---@field bright_red ansify.Style<"bright_red" , 91, "\27[91m">

---@field bright_green ansify.Style<"bright_green" , 92, "\27[92m">

---@field bright_blue ansify.Style<"bright_blue" , 94, "\27[94m">

---@field bright_cyan ansify.Style<"bright_cyan" , 96, "\27[96m">

---@field bright_magenta ansify.Style<"bright_magenta", 95, "\27[95m">

---@field bright_yellow ansify.Style<"bright_yellow" , 93, "\27[93m">

---@field bright_black ansify.Style<"bright_black" , 90, "\27[90m">

---@field bright_white ansify.Style<"bright_white" , 97, "\27[97m">

local foregrounds = {}

---@class ansify.backgrounds

---@field red ansify.Style<"on_red" , 41, "\27[41m">

---@field green ansify.Style<"on_green" , 42, "\27[42m">

---@field blue ansify.Style<"on_blue" , 44, "\27[44m">

---@field cyan ansify.Style<"on_cyan" , 46, "\27[46m">

---@field magenta ansify.Style<"on_magenta" , 45, "\27[45m">

---@field yellow ansify.Style<"on_yellow" , 43, "\27[43m">

---@field black ansify.Style<"on_black" , 40, "\27[40m">

---@field white ansify.Style<"on_white" , 47, "\27[47m">

---@field bright_red ansify.Style<"on_bright_red" , 101, "\27[101m">

---@field bright_green ansify.Style<"on_bright_green" , 102, "\27[102m">

---@field bright_blue ansify.Style<"on_bright_blue" , 104, "\27[104m">

---@field bright_cyan ansify.Style<"on_bright_cyan" , 106, "\27[106m">

---@field bright_magenta ansify.Style<"on_bright_magenta", 105, "\27[105m">

---@field bright_yellow ansify.Style<"on_bright_yellow" , 103, "\27[103m">

---@field bright_black ansify.Style<"on_bright_black" , 100, "\27[100m">

---@field bright_white ansify.Style<"on_bright_white" , 107, "\27[107m">

local backgrounds = {}

---

---ANSI text color and style helpers for building terminal strings.

---

---```lua

---local 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: "))

---```

---

---@class ansify

---@field modifiers ansify.modifiers

---@field foregrounds ansify.foregrounds

---@field backgrounds ansify.backgrounds

local ansify = {}

---

---Build a styled string from style names or exported style objects and text.

---

---```lua

---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**:

---

---* 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 such as `bright_red` and `on_bright_blue`.

---* The exported `foregrounds`, `backgrounds`, and `modifiers` tables expose

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

---* `modifiers.reset` is available for manual composition, but `"reset"` is not

--- a valid style name.

---

---@param style (ansify.Style|ansify.styleName)[] Style list containing style names and/or exported style objects.

---@param text string Text to render.

---@return string styled Styled text with a trailing ANSI reset.

---@nodiscard

function ansify.style(style, text) end

---

---Render inline style tags into ANSI text.

---

---```lua

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

---

---@param text string Text containing inline style tags like `{bold}` and `{red}`.

---@return string formatted Text with inline style tags resolved to ANSI output.

---@nodiscard

function ansify.format(text) end

---

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

---

---```lua

---local label = ansify.style({ "bold", "red" }, "ERROR")

---print(ansify.append(label, ": config missing"))

---```

---

---@param text string Existing text, optionally wrapped in ANSI styling.

---@param suffix string Text to append before the final reset when present.

---@return string appended Text with the suffix added.

---@nodiscard

function ansify.append(text, suffix) end

---

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

---

---```lua

---local message = ansify.style({ "bold", "red" }, "config missing")

---print(ansify.prepend(message, "ERROR: "))

---```

---

---@param text string Existing text, optionally wrapped in ANSI styling.

---@param prefix string Text to insert after the opening ANSI sequence when present.

---@return string prepended Text with the prefix added.

---@nodiscard

function ansify.prepend(text, prefix) end

---

---Extract a visible substring while preserving ANSI styling.

---

---```lua

---local text = ansify.style({ "red" }, "fatal error in config loader")

---print(ansify.slice(text, 7, 11))

---```

---

---@param text string Text that may contain ANSI escape sequences.

---@param start integer First visible character to keep.

---@param stop integer? Last visible character to keep.

---@return string sliced Visible substring with ANSI styling preserved.

---@nodiscard

function ansify.slice(text, start, stop) end

---

---Remove ANSI escape sequences from a string.

---

---```lua

---local styled = ansify.style({ "red" }, "error")

---print(ansify.strip(styled)) -- error

---```

---

---@param text string Text that may contain ANSI escape sequences.

---@return string stripped Text with ANSI SGR escape sequences removed.

---@nodiscard

function ansify.strip(text) end

---

---Check whether a string contains ANSI escape sequences.

---

---```lua

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

---print(ansify.has_ansi("plain")) -- false

---```

---

---@param text string Text that may contain ANSI escape sequences.

---@return boolean hasAnsi True when the text contains ANSI SGR escape sequences.

---@nodiscard

function ansify.has_ansi(text) end

---

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

---

---```lua

---local words = ansify.words(ansify.style({ "red" }, "build command failed"))

---print(words[1], words[2], words[3])

---```

---

---@param text string Text that may contain ANSI escape sequences.

---@return string[] words Visible words as individually renderable ANSI-aware fragments.

---@nodiscard

function ansify.words(text) end

---

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

---

---```lua

---local lines = ansify.lines(ansify.style({ "red" }, "one\ntwo"))

---print(lines[1], lines[2])

---```

---

---@param text string Text that may contain ANSI escape sequences and line breaks.

---@return string[] lines Visible lines as individually renderable ANSI-aware fragments.

---@nodiscard

function ansify.lines(text) end

---

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

---

---```lua

---local option = ansify.align(ansify.style({ "bold", "cyan" }, " --output <file>"), 22, "left")

---local description = "Write the rendered deployment report to a file instead of standardoutput."

---print(ansify.wrap(option .. description, 60))

---```

---

---@param text string Text that may contain ANSI escape sequences and line breaks.

---@param width integer Positive visible width to wrap to.

---@return string wrapped Wrapped text with ANSI styling preserved.

---@nodiscard

function ansify.wrap(text, width) end

---

---Count visible characters after ANSI escape sequences are removed.

---

---```lua

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

---```

---

---@param text string Text that may contain ANSI escape sequences.

---@return integer visibleLength Visible text length with ANSI escape sequences removed.

---@nodiscard

function ansify.len(text) end

---

---Align a string using visible width instead of raw byte length.

---

---```lua

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

---```

---

---@param text string Text that may contain ANSI escape sequences.

---@param width integer Visible width to pad to.

---@param direction 'left'|'right'|'center' Alignment direction.

---@return string aligned Text padded to the requested visible width.

---@nodiscard

function ansify.align(text, width, direction) end

---

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

---

---```lua

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

---```

---

---@param text string Text that may contain ANSI escape sequences.

---@param width integer Visible width to keep.

---@return string truncated Text truncated to the requested visible width.

---@nodiscard

function ansify.truncate(text, width) end

---

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

---

---```lua

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

---```

---

---@param value string String value to escape.

---@return string escaped String with ESC, newline, and tab escaped.

---@nodiscard

function ansify.escape(value) end

return ansify