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.
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.
Visit the xplr.util API docs for some useful utility / helper functions that you can use in your Lua function calls.
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
- initial_pwd
- vroot
- 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.
initial_pwd
Type: string
The initial working directory when xplr started.
vroot
Type: nullable string
The current virtual root.
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
Type: Explorer Config
The configuration for exploring paths.
history
Type: History
last_modes
Type: list of Mode
Last modes, not popped yet.
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
- uid
- gid
- canonical
- symlink
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.
uid
Type: integer
User ID of the file owner.
gid
Type: integer
Group ID of the file owner.
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.
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.
Explorer Config
Explorer config contains the following fields:
filters
List of filters to apply.
Type: list of Node Filter Applicable
sorters
Add list or sorters to the pipeline.
Type: list of Node Sorter Applicable
searcher
The searcher to use (if any).
Type: nullable Node Searcher Applicable