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.

Node

A node contains the following fields:

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.

created

Type: nullable integer

Creation time in nanosecond since UNIX epoch.

last_modified

Type: nullable integer

Last modification time in nanosecond since UNIX epoch.

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.

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.