Module terminal.utils

Support functions.

Constants

invalid_constant (value, constants[, prefix="Invalid value: "]) Returns an error message for an invalid lookup constant.
make_lookup ([value_type="value"], t) Converts a lookup table to a constant table with user friendly error reporting.
throw_invalid_constant (value, constants[, prefix="Invalid value: "[, err_lvl=1]]) Throws an error message for an invalid lookup constant.

Generic

resolve_index (index, max_value[, min_value=1]) Resolve indices.

Classes

class ([baseclass]) Creates a (sub)class.

Text

truncate_ellipsis (width[, text=""[, trunc_type="right"[, ellipsis="…"]]]) Truncates text to fit within a given width, adding ellipsis as needed.
utf8sub (str, i, j) Like string:sub, returns the substring of the string from i to j inclusive, but operates on utf8 characters.
utf8sub_col (str, i, j[, no_pad=false]) Like string:sub, returns the substring of the string from i to j inclusive, but operates on display columns.


Constants

invalid_constant (value, constants[, prefix="Invalid value: "])
Returns an error message for an invalid lookup constant. This function is used to generate error messages for invalid arguments.

Parameters:

  • value number or string The value that wasn't found.
  • constants table The valid values for the constant.
  • prefix string the prefix for the message. (default "Invalid value: ")

Returns:

    string The error message.
make_lookup ([value_type="value"], t)
Converts a lookup table to a constant table with user friendly error reporting. The constant table is modified in-place, a metatable with an __index metamethod is added to the table. This metamethod throws an error when an invalid key is accessed.

Parameters:

  • value_type string The type of value looked up, use a singular, eg. "cursor shape", or "foreground color". (default "value")
  • t table The lookup table.

Returns:

    table The same constant table t, with a metatable added.

Usage:

    local cursor_shape = M.make_lookup("cursor shape", {
  block = 0,
  underline = 1,
  bar = 2,
})

local value = cursor_shape["bad-shape"] -- throws an error;
-- Invalid cursor shape: "bad-shape". Expected one of: "block", "underline", "bar"
throw_invalid_constant (value, constants[, prefix="Invalid value: "[, err_lvl=1]])
Throws an error message for an invalid lookup constant. This function is used to generate error messages for invalid arguments.

Parameters:

  • value number or string The value that wasn't found.
  • constants table The valid values for the constant.
  • prefix string the prefix for the message. (default "Invalid value: ")
  • err_lvl number the error level when throwing the error. (default 1)

Returns:

    nothing, throws an error.

Generic

resolve_index (index, max_value[, min_value=1])
Resolve indices. This function resolves negative indices to positive indices. The result will be capped into the range [min_value, max_value].

Parameters:

  • index number The index to resolve.
  • max_value number The maximum value for the index.
  • min_value number The minimum value for the index. (default 1)

Classes

class ([baseclass])

Creates a (sub)class. This function creates a new class, which is a subclass of the given baseclass. An instance can be created by calling on the class, any parameteres passed in will be passed on to the init method. The init method (if present), will be called upon instantiation.

Every instance will:

  • have a super property, which points to the class itself.
  • upon creation call the init method (if present) with the parameters passed when calling on the Class.

Parameters:

  • baseclass class The base-class to inherit from. (optional)

Returns:

    table The new class.

Usage:

    local Cat = utils.class()
function Cat:init(value)
  self.value = value or 42
end

local Lion = utils.class(Cat)
function Lion:init(value)
  assert(self.super == Cat, "Superclass is not a Cat")
  Cat.init(self, value)   -- call ancestor initializer
  self.value = self.value * 2
end

local instance1 = Lion()
print(instance1.value)      --> 84
local instance2 = Lion(10)
print(instance2.value)      --> 20

Text

truncate_ellipsis (width[, text=""[, trunc_type="right"[, ellipsis="…"]]])
Truncates text to fit within a given width, adding ellipsis as needed. Shortens text if necessary, adds ellipsis when truncated. Respects UTF-8 character boundaries and handles double-width characters correctly.

Parameters:

  • width number The available width for the text in columns.
  • text string The text to truncate. (default "")
  • trunc_type string The type of truncation to apply: - "right": Truncate from the right, show beginning of text with ellipsis on the right - "left": Truncate from the left, show end of text with ellipsis on the left - "drop": Drop the entire text if it doesn't fit (return empty string). (default "right")
  • ellipsis string The ellipsis string to use. Defaults to Unicode ellipsis character "…". Can be a multi-character string or empty string. (default "…")

Returns:

  1. string The truncated text (may be empty string).
  2. number The size of the returned text in columns.

Usage:

    -- Truncate from right (default)
truncate_ellipsis(10, "Very long text")  -- "Very long…"
-- Truncate from left
truncate_ellipsis(10, "Very long text", "left")  -- "…long text"
-- Drop if too small
truncate_ellipsis(3, "Very long text", "drop")  -- ""
-- Custom ellipsis
truncate_ellipsis(10, "Very long text", "right", "..")  -- "Very lon.."
-- Empty string as ellipsis just truncates the text
truncate_ellipsis(10, "Very long text", "left", "")  -- " long text"
utf8sub (str, i, j)
Like string:sub, returns the substring of the string from i to j inclusive, but operates on utf8 characters.

Parameters:

  • str string the string to take the substring of
  • i number the starting index of the substring
  • j number the ending index of the substring

Returns:

    string the substring

Usage:

    -- UTF-8 double-width characters (Chinese, etc.)
utf8sub("你好", 1, 2)       -- "你好"
utf8sub("你好", 1, 1)       -- "你"
utf8sub("你好世界", 2, 3)    -- "好世"
utf8sub_col (str, i, j[, no_pad=false])
Like string:sub, returns the substring of the string from i to j inclusive, but operates on display columns. It uses text.width.utf8cwidth to determine the width of each character.

Parameters:

  • str string the string to take the substring of
  • i number the starting column of the substring (can't be negative!)
  • j number the ending column of the substring (can't be negative!)
  • no_pad boolean whether to pad the substring with spaces if the first or last column contains half of a double-width character (default false)

Returns:

    string the substring

Usage:

    -- UTF-8 double-width characters (2 columns each)
utf8sub_pos("你好世界", 3, 6)  -- "好世" (columns 3-6)
utf8sub_pos("你好世界", 2, 7)  -- " 好世 " (columns 2-7 with padding for half of double-width chars)
utf8sub_pos("你好世界", 2, 7, true)  -- "好世" (columns 2-7, no_pad == true)
generated by LDoc 1.5.0