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

As you noticed, the functions can accept any argument and return any result. However, the last function seems to follow a specific structure. It receives a special argument and returns a table of messages (the return is optional). 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["H"] = {
  help = "greet me",
  messages = {
    { CallLua = "custom.ask_name_and_greet" }
  }
}

Now, when we press H, when 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.

A list of handy utility functions

Here's a list of handy utility functions that might be useful when you are using the Lua API. You can either just copy-paste these functions in your ~/.config/xplr/init.lua, or create a utility module and require() it, or maybe create a plugin and share with the world.

-------- Function equivalent to basename in POSIX systems
xplr.fn.custom.basename = function(path)
  return string.gsub(path, "(.*/)(.*)", "%2")
end

-------- Function equivalent to dirname in POSIX systems
xplr.fn.custom.dirname = function(path)
  if str:match(".-/.-") then
    local name = string.gsub(path, "(.*/)(.*)", "%1")
    return name
  else
    return ''
  end
end

-------- Shell escape. See https://github.com/ncopa/lua-shell
xplr.fn.custom.shell_escape = function(args)
  local ret = {}
  for _,a in pairs(args) do
    local s = tostring(a)
    if s:match("[^A-Za-z0-9_/:=-]") then
      s = "'"..s:gsub("'", "'\\''").."'"
    end
    table.insert(ret,s)
  end
  return table.concat(ret, " ")
end

-------- Shell run. See https://github.com/ncopa/lua-shell
xplr.fn.custom.shell_run = function(args)
  local h = io.popen(xplr.fn.builtin.shell_escape(args))
  local outstr = h:read("*a")
  return h:close(), outstr
end

-------- Shell execute. See https://github.com/ncopa/lua-shell
xplr.fn.custom.shell_execute = function(args)
  return os.execute(xplr.fn.builtin.shell_escape(args))
end

add more