# 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` over `Call`, `BashExec0` over `BashExec` 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`. Use `xplr -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 themeing tips
- Tip: A list of handy utility functions
- Tip: Share tips and tricks working with Lua
- 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