Lua API

When xplr loads, it executes the built-in init.lua to set the default global values and then executes ~/.config/xplr/init.lua (or equivalent if any).

Before executing ~/.config/xplr/init.lua, xplr exposes a few customizable global Lua tables. They are -

xplr.config

This is the Lua representation of the Config object. You can modify this table simply by overwriting it.

For example:

xplr.config.general.show_hidden = true

xplr.fn

This table is further divided into xplf.fn.builtin and xplr.fn.custom.

xplr.fn.builtin

This is where the built-in Lua functions are defined. You can overwrite these functions but doing so is not recommended and may break things.

xplr.fn.custom

This is where you can define your own custom functions.

Example:

In ~/.config/xplr/init.lua, you can define

xplr.fn.custom.ask_name = function()
  print("What's your name?")
  return io.read()
end

xplr.fn.custom.greet = function(name)
  return "Hello " .. name .. "!"
end

xplr.fn.custom.ask_name_and_greet = function(app)
  local name = xplr.fn.custom.ask_name()
  local greeting = xplr.fn.custom.greet(name)

  local message = greeting .. " You are inside " .. app.pwd

  return {
    { LogSuccess = message },
    "Refresh"
  }
end

Here, as you can see, the functions can accept any argument and return any result. However, the last function seems to follow a specific structure. It receives an input and returns a table of messages. This is because we want to call this function from an action.

Let's go ahead and define the action.

xplr.config.modes.builtin.default.key_bindings.on_key["."] = {
  help = "greet me",
  messages = {
    { CallLua = "custom.ask_name_and_greet" }
  }
}

Now, when we press . in the default mode, it prompts for an input. When entered, we get a log message that greets us and tells us where we are. Using :l we can see all the logs.