Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pianocomposer321/officer.nvim
Like dispatch.vim but using overseer.nvim
https://github.com/pianocomposer321/officer.nvim
build-tool dispatch neovim-plugin-lua
Last synced: 7 days ago
JSON representation
Like dispatch.vim but using overseer.nvim
- Host: GitHub
- URL: https://github.com/pianocomposer321/officer.nvim
- Owner: pianocomposer321
- License: mit
- Created: 2024-01-09T01:25:24.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-01-13T22:00:53.000Z (10 months ago)
- Last Synced: 2024-08-02T06:23:44.350Z (3 months ago)
- Topics: build-tool, dispatch, neovim-plugin-lua
- Language: Lua
- Homepage:
- Size: 19.5 KB
- Stars: 19
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-neovim - pianocomposer321/officer.nvim - Like dispatch.vim but using overseer.nvim. (Code Runner / Quickfix)
README
# officer.nvim
Like dispatch.vim but using overseer.nvim.
https://github.com/pianocomposer321/officer.nvim/assets/54072354/d0d49fd0-1b23-4936-aec1-80459bd2ef5e
## About
Officer.nvim is an alternative to tpope's vim-dispatch. Like dispatch, it allows you to
run programs asynchronously either using `:h makeprg` or using an arbitrary command.
Officer does not aim to be a drop-in replacment for dispatch however. In particular,
although there are equivalents of both the `:Make` and `:Start` commands (`:Make` and `:Run`),
there is no equivalent of the `:Dispatch` command, and at this point I do not plan to add it.
Officer uses [overseer.nvim](https://github.com/stevearc/overseer.nvim) to run
tasks under the hood. This means that it benefits from overseer's task
management utilities (such as the task list) and modularity. You can customize
the behavior of tasks started from officer by changing the components that are
added to the overseer tasks. For more on this see the [configuration](#config)
section, and also read overseer.nvim's documentation.
The idea is that you can do things "the vim way" (using `:h :compiler` and `:h
makeprg` to compile your program) without having to sacrifice the modern
convienineces of neovim's lua ecosystem.
## Setup
- lazy.nvim (recommended):
```lua
{
"pianocomposer321/officer.nvim",
dependencies = "stevearc/overseer.nvim",
config = function()
require("officer").setup {
-- config
}
end,
},
```
## Config
Variable
Type/Default
Description
components
table
OR
fun(params: table): table
Default: {}
These are the components that are added to the overseer task.
If use_base_components is true, these components
will be appended to the base_components table,
otherwise, they will replace it.
If this is a function, it accepts one argument and returns the components.
The argument is a table with information about the invocation of the :Make
or :Run command. This is the same table that is passed to the function given
to nvim_create_user_command(). See :h nvim_create_user_command()
for more information.
use_base_components
boolean
Default: true
If this is true, each overseer task will use a base set of components.
Set this to false if you want to add your own components through the components
config value that will replace the base components.
Warning: many aspects of the plugin expect the base components to be there.
Setting this value to false may have unexpected results.
create_commands
boolean
Default: true
Whether to create the :Make and :Run commands.
See "Commands"
create_mappings
boolean
Default: false
Whether to create the suggested mappings. See "Mappings".
## Usage
### Commands
- `:Make [args]`
Run `:h makeprg` with `args` in a terminal window that opens to the side.
On completion, parse errors into the quickfix list using `:h errorformat`. If
there are recognized errors, open the quickfix list.
- `:Make! [args]`
Like `:Make [args]`, but don't open the quickfix list, and close the terminal window
on completion.
- `:Run[!] {command} [args]`
Like `:Make[!]`, but run `command` instead of `:h makeprg`.
### Mappings
> **🛈** These mappings are not applied by default. Set `create_mappings` to true in your config to
use them. Or feel free to create your own mappings instead :).
Suggested Mappings:
| RHS | LHS |
|-----------|------------------|
| `m`| `:Make` |
| `m` | `:Make` |
| `m!` | `:Make!` |
| `M`| `:Run` |
| `M` | `:Run` |
| `M!` | `:Run!` |
## Example
Here is a custom component that I have for all of my officer tasks. It keeps track
of the task history and allows you to restart the most recent one with a keybinding.
#### Setup call:
```lua
require("officer").setup {
create_mappings = true,
components = { "user.track_history" },
}
```
#### Mapping:
```lua
vim.keymap.set("n", "", require("user.overseer_util").restart_last_task)
```
~/.config/nvim/lua/overseer/component/user/track_history.lua
```lua
local util = require("user.overseer_util")
return {
desc = "Track files in a history so that the most recent can be restarted",
constructor = function()
return {
on_start = function(_, task)
util.register_task(task)
end,
on_dispose = function(_, task)
util.unregister_task(task.id)
end,
}
end,
}
```
~/.config/nvim/lua/user/overseer_util.lua
```lua
local M = {}
local task_history = {}
local tasks = {}
function M.register_task(task)
tasks[task.id] = task
table.insert(task_history, task.id)
end
function M.get_last_task()
return tasks[task_history[#task_history]]
end
function M.restart_last_task()
local task = M.get_last_task()
if task then
require("overseer").run_action(task, "restart")
end
end
function M.unregister_task(task_id)
tasks[task_id] = nil
if task_history[#task_history] == task_id then
task_history[#task_history] = nil
end
end
return M
```