Lua Function Calls

xplr allows you to define lua functions using the xplr.fn.custom Lua API.

These functions can be called using messages like CallLua, CallLuaSilently.

When called the function receives a special argument that contains some useful information. The function can optionally return a list of messages which will be handled by xplr.

Lua Context

This is a special argument passed to the lua functions when called using the CallLua, CallLuaSilently messages.

It contains the following information:

version

Type: string

xplr version. Can be used to test compatibility.

pwd

Type: string

The present working directory/

focused_node

Type: nullable Node

The node under focus.

directory_buffer

Type: nullable Directory Buffer

The directory buffer being rendered.

selection

Type: list of selected Nodes

The selected nodes.

mode

Type: Mode

Current mode.

layout

Type: Layout

Current layout.

input_buffer

Type: nullable string

The input buffer.

pid

Type: integer

The xplr session PID.

session_path

Type: string

The session path.

explorer_config

TODO

history

Type: History

last_modes

Type: list of Mode

Last modes, not popped yet.

parent

Type: string

The parent path of the node.

relative_path

Type: string

The path relative to the parent, i.e. the file/directory name with extension.

absolute_path

Type: string

The absolute path (without resolving symlinks) of the node.

extension

Type: string

The extension of the node.

Type: boolean

true if the node is a symlink.

is_broken

Type: boolean

true if the node is a broken symlink.

is_dir

Type: boolean

true if the node is a directory.

is_file

Type: boolean

true if the node is a file.

is_readonly

Type: boolean

true if the node is real-only.

mime_essence

Type: string

The mime type of the node. For e.g. text/csv, image/jpeg etc.

size

Type: integer

The size of the exact node. The size of a directory won't be calculated recursively.

human_size

Type: string

Like size but in human readable format.

permissions

Type: Permission

The permissions applied to the node.

canonical

Type: nullable Resolved Node Metadata

If the node is a symlink, it will hold information about the symlink resolved node. Else, it will hold information the actual node. It the symlink is broken, it will be null.

Type: nullable Resolved Node Metadata

If the node is a symlink and is not broken, it will hold information about the symlink resolved node. However, it will never hold information about the actual node. It will instead be null.

Node

A node contains the following fields:

Directory Buffer

Directory buffer contains the following fields:

parent

Type: string

The parent path of the node.

nodes

Type: list of Nodes

A list of visible nodes.

total

Type: int

The count of nodes being rendered.

focus

Type: int

The index of the node under focus. It can be 0 even when there's no node to focus on.

History

History contains the following fields:

loc

Type: int

Location of the current path in history.

paths

Type: list of string

Visited paths.

Example: Using Lua Function Calls

-- Define the function
xplr.fn.custom.ask_name_and_greet = function(app)
  print("What's your name?")

  local name = io.read()
  local greeting = "Hello " .. name .. "!"
  local message = greeting .. " You are inside " .. app.pwd

  return {
    { LogSuccess = message },
  }
end

-- Map the function to a key (space)
xplr.config.modes.builtin.default.key_bindings.on_key.space = {
  help = "ask name and greet",
  messages = {
    { CallLua = "custom.ask_name_and_greet" }
  }
}

-- Now, when you press "space" in default mode, you will be prompted for your
-- name. Enter your name to receive a nice greeting and to know your location.