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
- pwd
- focused_node
- directory_buffer
- selection
- mode
- layout
- input_buffer
- pid
- session_path
- explorer_config
- history
- last_modes
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
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.
is_symlink
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.
symlink
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:
- parent
- relative_path
- absolute_path
- extension
- is_symlink
- is_broken
- is_dir
- is_file
- is_readonly
- mime_essence
- size
- human_size
- permissions
- created
- last_modified
- canonical
- symlink
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.