Global Functions

Global functions and variables available in Yazi Lua plugins

Global Variables

cx

The context object containing the current application state. See Context API for details.

local hovered = cx.active.current.hovered
local tabs = cx.tabs

plugin

The current plugin’s module table (available in plugin context).

local config = plugin.config

Global Functions

Err(format, ...)

Create a custom error with formatted message.

format · string · required

Format string (printf-style)

... · any

Format arguments

return · Error

Custom error object

return nil, Err("Failed to process %s", filename)

Helper Functions (from ya.lua)

These utility functions are available globally via the ya namespace:

ya.clamp(min, x, max)

Clamp a value between minimum and maximum.

min · number · required

Minimum value

x · number · required

Value to clamp

max · number · required

Maximum value

return · number

Clamped value

local skip = ya.clamp(0, cx.active.preview.skip + step, bound)

ya.list_merge(a, b)

Merge list b into list a (modifies a).

a · table · required

Target list

b · table · required

Source list

return · table

The modified list a

local items = ya.list_merge(base_items, extra_items)

ya.dict_merge(a, b)

Merge dictionary b into dictionary a (modifies a).

a · table · required

Target dictionary

b · table · required

Source dictionary

return · table

The modified dictionary a

local opts = ya.dict_merge(default_opts, user_opts)

ya.readable_size(size)

Format byte size as human-readable string.

size · number · required

Size in bytes

return · string

Formatted size (e.g., “1.5M”, “3.2G”)

local size_str = ya.readable_size(file.cha.len)
-- "1.5M"

ya.readable_path(path)

Format path with ~ for home directory.

path · string · required

Absolute path

return · string

Path with ~ prefix if under home directory

local display = ya.readable_path("/home/user/documents")
-- "~/documents"

ya.child_at(pos, children)

Find the child element at the given position.

pos · table · required

Position {x, y} or Pos object

children · table · required

List of child elements with _area field

return · table|nil

The child element at the position, or nil

local child = ya.child_at({x = 10, y = 5}, components)

Environment Variables

Access environment variables using Lua’s os.getenv():

local home = os.getenv("HOME") or os.getenv("USERPROFILE")
local editor = os.getenv("EDITOR") or "vim"

String Functions

Lua’s standard string library is available:

local ext = string.lower(file.url:match("%.([^.]+)$") or "")
local name = string.format("%s.%s", base, ext)

Table Functions

Lua’s standard table library is available:

table.insert(items, new_item)
table.sort(items, function(a, b) return a.name < b.name end)

Math Functions

Lua’s standard math library is available:

local max_width = math.max(100, area.w)
local cols = math.floor(area.w / item_width)