🎨 Terminal text styling library for Lua

The name of this library is based on a word "warna", which means color in Indonesian language. Why did I choose this? Cuz I'm an Indonesian :P

Run the following command to install Warna.

$ luarocks install warna

You might also wanted to install the types definition if you're using Teal.

$ luarocks install warna-tl

Copy warna.lua (and warna.d.tl if you're also using Teal) from repository tree to the path where Lua can find and require it.

{
    level: integer = --[[ Automatically detected ]],
}

• Fields:

  • level: integer: Specifies the level of color support.

    • -1 — Disable escape sequences completely.
    • 0 — Disable color support.
    • 1 — Basic color support. (8-16 colors)
    • 2 — 256 colors support.
    • 3 — Truecolor support. (16 million colors)
      

    By default, the field value is automatically detected.
    Can be overridden by setting NO_COLOR environment variable, FORCE_COLOR environment variable, or directly setting the field itself.

{
    colors = { [string]: function(string...): string?|string|number },
    [string]: function(string...): string?|string|number
}

• Fields:
  • [string]: function(string...): string?|string|number: For attributes that requires options.level >= 0
  • colors[string]: function(string...): string?|string|number: For attributes that requires options.level >= 1
    • function(string...): string? If the attribute accepts attribute parameters (implying the string...) or it's dynamic attribute and returns an escape sequence.
    • string|number If the attribute is static, the value of the field is automatically tostring'ed.

All fields in attributes are documented in the list of attributes section.

function windows_patch_vte(skip_registry: boolean): boolean, string

• Parameters:
  • skip_registry: boolean: Skip editing the registry.
• Returns:
  • boolean: Wether it successfully enable VTE.
  • string: What method does the function used for enabling VTE.

Patch the Windows VT color sequences problem.

Requires Windows 10 build after 14393 (Anniversary update) and ffi or cffi library to patch. If not fallbacks to editing registry.

For Windows 10 before build 14393 (Anniversary update) or before Windows 10, requires ANSICON to patch.

function raw_apply(str: string, attrs: string[]): string

• Parameters:
  • str: string: String to be applied with attributes.
  • attrs: string[] List of attributes. Follows the syntax of an attribute.
• Returns:
  • string: The applied string.

Apply attributes to a string.

function apply(str: string, attrs: string[]): string

• Parameters:
  • str: string: String to be applied with attributes.
  • attrs: string[] List of attributes. Follows the syntax of an attribute.
• Returns:
  • string: The applied string.

Similar to raw_apply, except the string has reset attribute appended.

function raw_format(fmt: string): string

• Parameters:
  • fmt: string: String containing format specifier.
• Returns:
  • string: The formatted string.

Format a string containing format specifier.

function format(fmt: string): string

• Parameters:
  • fmt: string: String containing format specifier.
• Returns:
  • string: The formatted string.

Similar to raw_format, except the string has reset attribute appended.

function strip_escapes(str: string): string

• Parameters:
  • str: string: String containing ESC[...m.
• Returns:
  • string: Stripped string.

Strip a string containing escape sequences (ESC[...m).

You can also run the warna.lua as CLI, which acts as a helper for styling text in shell script.

Usage: warna.lua <flags>
       warna.lua <fmt|text> [<attributes...>]
       warna.lua -b <fmt|text> [<attributes...>]
       warna.lua -f <fmt>
       warna.lua -a <text> [<attributes...>]

Flags: * -h -- Prints the command usage
       * -r -- Don't skip editing registry when enabling VTE in Windows.
       * -b -- Both format the text and apply attributes to the text (Default if a flag isn't supplied)
       * -f -- Format the text
       * -a -- Apply the text with attributes

<flags> can be stack up as many as you want. e.g `-ar 'My Text' red`.

Accepts NO_COLOR and FORCE_COLOR to manipulate color support.

The format specifier is similar to ansicolors.lua. The following text uses LPEG's re expression to specify the format syntax.

format <- ('%{' / '%%{') %s* attributes? %s* '}'
attributes <- attribute (' '^+1 attribute)*
attribute <- [a-zA-Z-]+ (':' [^,; ]^-0 ((',' / ';') [^,; ]^-0)*)?

• Basic attributes
  Enabled by default, i.e only enabled if options.level >= 0.
  • reset
  • bright or bold
  • dim or dark
  • italic
  • underline or underl
  • blink
  • inverse or reverse
  • hidden or invisible
  • strikethrough or strike

• Color attributes
  Only enabled if options.level >= 1.

  • black
  • red
  • green
  • yellow
  • blue
  • magenta
  • cyan
  • white
  • default

• More color attributes
  Certain color attributes only enabled if options.level >= 2 or options.level >= 3.

  • color256:(ncolor) (Only enabled if options.level >= 2)
    • ncolor: The Xterm 256 colors.
  • rgb:(r),(g),(b) (Only enabled if options.level >= 3)
    • r,g,b: RGB code.
  • hex:(hex) (Only enabled if options.level >= 3)
    • hex: Hex color code.