pianocomposer321/officer.nvim

github github
code-runner
stars 15
issues 0
subscribers 1
forks 0
CREATED

2024-01-09

UPDATED

2 months ago


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 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 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):
{
  "pianocomposer321/officer.nvim",
  dependencies = "stevearc/overseer.nvim",
  config = function()
    require("officer").setup {
      -- config
    }
  end,
},

Config

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<SPACE> :Make<SPACE>
m<CR> :Make<CR>
m! :Make!<SPACE>
M<SPACE> :Run<SPACE>
M<CR> :Run<CR>
M! :Run!<SPACE>

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:

require("officer").setup {
  create_mappings = true,
  components = { "user.track_history" },
}

Mapping:

vim.keymap.set("n", "<LEADER><CR>", require("user.overseer_util").restart_last_task)
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,
}
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