> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sxyazi/yazi/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](cx) for details.

```lua theme={null}
local hovered = cx.active.current.hovered
local tabs = cx.tabs
```

### `plugin`

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

```lua theme={null}
local config = plugin.config
```

## Global Functions

### `Err(format, ...)`

Create a custom error with formatted message.

<ParamField path="format" type="string" required>
  Format string (printf-style)
</ParamField>

<ParamField path="..." type="any">
  Format arguments
</ParamField>

<ResponseField name="return" type="Error">
  Custom error object
</ResponseField>

```lua theme={null}
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.

<ParamField path="min" type="number" required>
  Minimum value
</ParamField>

<ParamField path="x" type="number" required>
  Value to clamp
</ParamField>

<ParamField path="max" type="number" required>
  Maximum value
</ParamField>

<ResponseField name="return" type="number">
  Clamped value
</ResponseField>

```lua theme={null}
local skip = ya.clamp(0, cx.active.preview.skip + step, bound)
```

### `ya.list_merge(a, b)`

Merge list `b` into list `a` (modifies `a`).

<ParamField path="a" type="table" required>
  Target list
</ParamField>

<ParamField path="b" type="table" required>
  Source list
</ParamField>

<ResponseField name="return" type="table">
  The modified list `a`
</ResponseField>

```lua theme={null}
local items = ya.list_merge(base_items, extra_items)
```

### `ya.dict_merge(a, b)`

Merge dictionary `b` into dictionary `a` (modifies `a`).

<ParamField path="a" type="table" required>
  Target dictionary
</ParamField>

<ParamField path="b" type="table" required>
  Source dictionary
</ParamField>

<ResponseField name="return" type="table">
  The modified dictionary `a`
</ResponseField>

```lua theme={null}
local opts = ya.dict_merge(default_opts, user_opts)
```

### `ya.readable_size(size)`

Format byte size as human-readable string.

<ParamField path="size" type="number" required>
  Size in bytes
</ParamField>

<ResponseField name="return" type="string">
  Formatted size (e.g., "1.5M", "3.2G")
</ResponseField>

```lua theme={null}
local size_str = ya.readable_size(file.cha.len)
-- "1.5M"
```

### `ya.readable_path(path)`

Format path with `~` for home directory.

<ParamField path="path" type="string" required>
  Absolute path
</ParamField>

<ResponseField name="return" type="string">
  Path with `~` prefix if under home directory
</ResponseField>

```lua theme={null}
local display = ya.readable_path("/home/user/documents")
-- "~/documents"
```

### `ya.child_at(pos, children)`

Find the child element at the given position.

<ParamField path="pos" type="table" required>
  Position `{x, y}` or Pos object
</ParamField>

<ParamField path="children" type="table" required>
  List of child elements with `_area` field
</ParamField>

<ResponseField name="return" type="table|nil">
  The child element at the position, or nil
</ResponseField>

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

## Environment Variables

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

```lua theme={null}
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:

```lua theme={null}
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:

```lua theme={null}
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:

```lua theme={null}
local max_width = math.max(100, area.w)
local cols = math.floor(area.w / item_width)
```