Writing Plugins
Anyone who can write Lua code, can write xplr plugins.
Just follow the instructions and best practices:
Naming
xplr plugins are named using hiphen (-
) separated words that may also include
integers. They will be plugged using the require()
function in Lua.
Structure
A minimal plugin should confirm to the following structure:
.
├── README.md
└── init.lua
You can also use this template.
README.md
This is where you document what the plugin does, how to use it, etc.
init.lua
This file is executed to load the plugin. It should expose a setup()
function, which will be used by the users to setup the plugin.
Example:
local function setup(args)
local xplr = xplr
-- do stuff with xplr
end
return { setup = setup }
Publishing
When publishing plugins on GitHub or other repositories, it's a best practice
to append .xplr
to the name to make them distinguishable. Similar to the
*.nvim
naming convention for Neovim plugins.
Finally, after publishing, don't hesitate to let us know.
Best practices
- Try not to execute a lot of commands at startup, it may make xplr slow to start.
- When executing commands, prefer
Call0
overCall
,BashExec0
overBashExec
and so on. File names may contain newline characters (e.g.foo$'\n'bar
). - File names may also contain quotes. Avoid writing directly to
$XPLR_PIPE_MSG_IN
. Usexplr -m
/xplr --pipe-msg-in
instead. - Check for empty variables using the syntax
${FOO:?}
or use a default value${FOO:-defaultvalue}
.
Examples
Visit Awesome Plugins for xplr plugin examples.
Also See
- Tip: A list of hacks yet to make it as Lua plugins
- Tip: Some UI and theming tips
- Tutorial: Adding a New Mode
- Example: Using Environment Variables and Pipes
- Example: Using Lua Function Calls
- Example: Defining Custom Layout
- Example: Customizing Table Renderer
- Example: Render a custom dynamic table
- Example: Implementing a directory visit counter