Module terminal.text

Terminal text module.

Provides utilities to set text attributes in terminals.

The text attribute-sets conform to the following format:

local attr = {
  fg         = nil, -- foreground color (string, or extended color number)
  fg_r       = nil, -- red value of foreground color
  fg_g       = nil, -- green value of foreground color
  fg_b       = nil, -- blue value of foreground color
  bg         = nil, -- background color (string, or extended color number)
  bg_r       = nil, -- red value of background color
  bg_g       = nil, -- green value of background color
  bg_b       = nil, -- blue value of background color
  brightness = nil, -- brightness level (see brightness_seq for details)
  underline  = nil, -- underline (boolean)
  blink      = nil, -- blink (boolean)
  reverse    = nil, -- reverse colors (boolean)
}

The base colors strings (for fg and bg) are: black, red, green, yellow, blue, magenta, cyan, and white.

All elements are optional. If an element is omitted, it will be taken from the current top of the stack.

Functions

attr (attr) Sets all text attributes/colors and writes it to the terminal.
blink ([on=true]) (Un)sets the blink attribute and writes it to the terminal.
brightness (brightness) Sets the brightness and writes it to the terminal.
reverse ([on=true]) (Un)sets the reverse attribute and writes it to the terminal.
underline ([on=true]) (Un)sets the underline attribute and writes it to the terminal.

Sequences

attr_seq (attr) Creates an ansi sequence to set all text attributes/colors without writing it to the terminal.
blink_seq ([on=true]) Creates an ansi sequence to (un)set the blink attribute without writing it to the terminal.
brightness_seq (brightness) Creates an ansi sequence to set the brightness without writing it to the terminal.
reverse_seq ([on=true]) Creates an ansi sequence to (un)set the reverse attribute without writing it to the terminal.
underline_seq ([on=true]) Creates an ansi sequence to (un)set the underline attribute without writing it to the terminal.

Stack based functions

apply () Re-applies the current attributes/colors (at the top of the stack), and writes it to the terminal.
apply_seq () Re-applies the current attributes/colors (at the top of the stack), returns the sequence without writing to the terminal.
pop ([n=1]) Pops n attributes/colors off the stack, and writes the last one to the terminal.
pop_seq ([n=1]) Pops n attributes/colors off the stack (and returns the last one), without writing it to the terminal.
push (attr) Pushes the given attributes/colors onto the stack, and writes an ansi sequence to set the new attributes to the terminal.
push_seq (attr) Pushes the given attributes/colors onto the stack, and returns an ansi sequence to set the new attributes without writing it to the terminal.


Functions

attr (attr)
Sets all text attributes/colors and writes it to the terminal. Every element omitted in the attr table will be taken from the current top of the stack.

Parameters:

  • attr table the attributes to set, see attrs for details.

Returns:

    true

Usage:

    terminal.text.attr({
  fg = "red",
  bg = "black",
  brightness = 3,
  underline = true,
  blink = false,
  reverse = false
})
blink ([on=true])
(Un)sets the blink attribute and writes it to the terminal.

Parameters:

  • on boolean whether to set blink (default true)

Returns:

    true
brightness (brightness)
Sets the brightness and writes it to the terminal.

Parameters:

  • brightness string or integer the brightness to set

Returns:

    true
reverse ([on=true])
(Un)sets the reverse attribute and writes it to the terminal.

Parameters:

  • on boolean whether to set reverse (default true)

Returns:

    true
underline ([on=true])
(Un)sets the underline attribute and writes it to the terminal.

Parameters:

  • on boolean whether to set underline (default true)

Returns:

    true

Sequences

attr_seq (attr)
Creates an ansi sequence to set all text attributes/colors without writing it to the terminal. Only set what you change. Every element omitted in the attr table will be taken from the current top of the stack.

Parameters:

  • attr the attributes to set, with keys:
    • fg string or integer the foreground color to set. Base color (string), or extended color (number). Takes precedence of fg_r, fg_g, fg_b. (optional)
    • fg_r integer the red value of the foreground color to set. (optional)
    • fg_g integer the green value of the foreground color to set. (optional)
    • fg_b integer the blue value of the foreground color to set. (optional)
    • bg string or integer the background color to set. Base color (string), or extended color (number). Takes precedence of bg_r, bg_g, bg_b. (optional)
    • bg_r integer the red value of the background color to set. (optional)
    • bg_g integer the green value of the background color to set. (optional)
    • bg_b integer the blue value of the background color to set. (optional)
    • brightness string or number the brightness level to set (optional)
    • underline boolean whether to set underline (optional)
    • blink boolean whether to set blink (optional)
    • reverse boolean whether to set reverse (optional)

Returns:

    string ansi sequence to write to the terminal

Usage:

    local str = terminal.text.attrs({
  fg = "red",
  bg = "black",
  brightness = 3,
  underline = true,
  blink = false,
  reverse = false
})
blink_seq ([on=true])
Creates an ansi sequence to (un)set the blink attribute without writing it to the terminal.

Parameters:

  • on boolean whether to set blink (default true)

Returns:

    string ansi sequence to write to the terminal
brightness_seq (brightness)

Creates an ansi sequence to set the brightness without writing it to the terminal. brightness can be one of the following:

  • 0, "off", or "invisble" for invisible
  • 1, "low", or "dim" for dim
  • 2, "normal" for normal
  • 3, "high", "bright", or "bold" for bright

Parameters:

  • brightness string or integer the brightness to set

Returns:

    string ansi sequence to write to the terminal
reverse_seq ([on=true])
Creates an ansi sequence to (un)set the reverse attribute without writing it to the terminal.

Parameters:

  • on boolean whether to set reverse (default true)

Returns:

    string ansi sequence to write to the terminal
underline_seq ([on=true])
Creates an ansi sequence to (un)set the underline attribute without writing it to the terminal.

Parameters:

  • on boolean whether to set underline (default true)

Returns:

    string ansi sequence to write to the terminal

Stack based functions

These functions provide direct access to the cursor position stack.
apply ()
Re-applies the current attributes/colors (at the top of the stack), and writes it to the terminal.

Returns:

    true
apply_seq ()
Re-applies the current attributes/colors (at the top of the stack), returns the sequence without writing to the terminal.

Returns:

    string ansi sequence to write to the terminal
pop ([n=1])
Pops n attributes/colors off the stack, and writes the last one to the terminal.

Parameters:

  • n number number of attributes to pop (default 1)

Returns:

    true
pop_seq ([n=1])
Pops n attributes/colors off the stack (and returns the last one), without writing it to the terminal.

Parameters:

  • n number number of attributes to pop (default 1)

Returns:

    string ansi sequence to write to the terminal
push (attr)
Pushes the given attributes/colors onto the stack, and writes an ansi sequence to set the new attributes to the terminal. Every element omitted in the attr table will be taken from the current top of the stack.

Parameters:

  • attr table the attributes to set, see text.attrs for details.

Returns:

    true
push_seq (attr)
Pushes the given attributes/colors onto the stack, and returns an ansi sequence to set the new attributes without writing it to the terminal. Every element omitted in the attr table will be taken from the current top of the stack.

Parameters:

  • attr table the attributes to set, see text.attrs for details.

Returns:

    string ansi sequence to write to the terminal
generated by LDoc 1.5.0