# extregs.nvim

Useful extended registers for a Neovim build with `has('extregs')`.

## Install

Add the repo to `vim.pack.add({...})`. The plugin automatically calls `setup()`.
For options, instead call `require('extregs').setup({...})` from an earlier startup
config file (before Neovim loads `plugin/` runtime files):

```lua
require('extregs').setup({
  file = { path = '/var/run/user/' .. vim.env.USER .. '/nvim.regfile' },
  ssh = { host = 'rahm@photon', path = '~/.local/state/nvim/regfile' },
  tmux = { buffer = nil }, -- nil: most recent paste buffer
  timestamp = { format = '%Y-%m-%dT%H:%M:%S%z' },
})
```

The plugin registers `osc52`, `tmux`, `buffer`, `file.basename`, `file.stem`,
`file.dirname`, `file.backed`, `ssh.backed`, `timestamp`, and `uuid`.
For extreg syntax use your Neovim patch's `~name` register notation.

### tmux paste buffer

`~tmux` reads and writes tmux's current paste buffer. A write runs
`tmux load-buffer -` and a read runs `tmux show-buffer`.
Set `tmux = { buffer = 'nvim' }` to use a named tmux buffer instead.
The content is ordinary text so it can be pasted with tmux's normal paste
binding; no JSON cookie is written. Reading follows the same plaintext rule
as backed-register reads: one line is characterwise, multiple lines linewise.
Writing a linewise register appends a newline. tmux must be accessible from
Neovim (`TMUX` or a compatible tmux environment).

### Backed-register format

A structured write produces:

```
NVIM_EXTREGS_JSON_V1
{"lines":["hello"],"type":"v"}
```

A read without that first-line magic cookie treats the whole file as plain
text: one line → characterwise (`v`); multiple lines → linewise (`V`).

### Limitations

- The source buffer is replaced in memory by `buffer` writes; saving it is separate.
- OSC 52 clipboard reads are terminal-dependent and may time out or fail.
- SSH calls are synchronous, and `ssh.backed` requires passwordless SSH.
- Filename registers are read-only in this initial implementation (as are timestamp/uuid).
- Register callbacks rely on a custom, unreleased Neovim API; validate against your
  exact extregs branch before using this in production.
- Missing `has('extregs')` yields a scheduled error notification (not a blocking
  error prompt), and registration is skipped.

### Provider architecture

Every register has a dedicated module under `lua/extregs/`. Each module exposes
`get_provider(cfg)` and returns a provider object with `read()` and `write(reg)`
methods. The initializer alone owns registration, error notifications, and the
`has('extregs')` guard. To add a register, create a provider module and add one
entry to the `providers` table in `lua/extregs/init.lua`.

```lua
local provider = require('extregs.tmux').get_provider(cfg.tmux)
-- The initializer wraps these with error handling and registers them:
vim._extregs.register('tmux',
  function(reg) return provider:write(reg) end,
  function() return provider:read() end)
```

The original yank and put callback argument ordering is preserved. The
shared `storage.lua` serializer is used by both file-backed providers.